Shopify 商品 CSV 格式要求

整理自 Shopify 官方對商品 CSV 的要求,並列出本檢查工具針對每項要求所做的檢查。最近一次與 Shopify 說明中心核對的日期為 2026年10月29日,以 Shopify 官方最新內容為準。

檔案格式

儲存為 UTF-8

Shopify 只讀取 UTF-8 編碼的檔案。其他編碼會讓重音字母、彎引號和中文等字元變成亂碼,或導致 “Illegal quoting” 錯誤。

用半形逗號分隔欄位

每個欄位之間必須用半形逗號分隔。部分 Excel 版本會用分號匯出,Shopify 無法讀取。

使用半形直引號

含有逗號的值必須用半形直引號(")括起來。彎引號或缺少引號會破壞整列。

單一檔案不超過 15 MB

商品 CSV 不能超過 15 MB,商品較多時請拆成多個檔案。

不要將檔案排序

在試算表軟體中排序可能讓款式和圖片與所屬商品分離。匯入排序過的檔案可能以錯誤資料覆寫商品,且無法復原。

資料列結構

一項有兩個款式、兩張圖片的商品
列類型URL handleTitleOption1 nameOption1 valueSKUPriceProduct image URLImage position
商品linen-shirtLinen shirtSizeSLS-S39.00https://…/front.jpg1
款式linen-shirtMLS-M39.00
圖片linen-shirthttps://…/back.jpg2

第一列:商品

商品的第一列填寫所有商品資訊、第一個款式和第一張圖片。

後續列:款式

每個額外的款式佔一列,填寫相同的 URL handle;這些列的 Title、Description、Vendor、Tags 留空。

圖片列

每張額外的圖片佔一列,只填寫 URL handle 和圖片資訊。

一個 handle 對應一項商品

同一個 handle 在檔案中再次作為新商品出現時,Shopify 會忽略它;沒有任何一列有 Title 的 handle 也會被忽略。

各欄位說明

欄位名稱舊版名稱要求取值或上限
TitleShopify 官方說明—必要。顯示給顧客的商品名稱,只在商品第一列填寫。
URL handleShopify 官方說明Handle商品的唯一識別碼,用於商品網址。只能包含字母、數字和連字號,不能有空格。商品的每一列都要填寫。
DescriptionShopify 官方說明Body (HTML)商品說明,可以使用 HTML。
VendorShopify 官方說明—品牌或供應商名稱。
Product categoryShopify 官方說明Product Category, Standardized Product Type必須對應 Shopify 標準商品分類,填寫完整路徑或類別 ID。
TypeShopify 官方說明Custom Product Type自訂的商品類型,用於整理商品,可填任意文字。
TagsShopify 官方說明—多個標籤用逗號分隔,使用字母、數字和連字號。最多 250 個標籤
Published on online storeShopify 官方說明Published是否在網路商店上顯示,預設 true。truefalse
StatusShopify 官方說明—如果包含此欄位,每項商品都必須填寫;不包含此欄位時預設為 active。activedraftarchived
SKUShopify 官方說明Variant SKU款式的 SKU。款式使用自訂出貨服務時必須填寫。
Variant BarcodesShopify 官方說明Barcodes, Variant Barcode, Barcode多個條碼用分號分隔,可加 gtin:、upc: 等類型前綴。最多 20 個條碼
Option1 nameShopify 官方說明Option1 Name選項名稱,如 Size。沒有款式的商品填 Title。最多 3 個選項
Option1 valueShopify 官方說明Option1 Value此款式的選項值。沒有款式的商品填 Default Title。
Option1 Linked ToShopify 官方說明Option1 LinkedTo把選項連結到類別中繼欄位:product.metafields.shopify.屬性名稱。
Option2 nameShopify 官方說明Option2 Name第二個選項名稱。
Option2 valueShopify 官方說明Option2 Value此款式的第二個選項值。
Option2 Linked ToShopify 官方說明Option2 LinkedTo第二個選項連結的類別中繼欄位。
Option3 nameShopify 官方說明Option3 Name第三個選項名稱。
Option3 valueShopify 官方說明Option3 Value此款式的第三個選項值。
Option3 Linked ToShopify 官方說明Option3 LinkedTo第三個選項連結的類別中繼欄位。
PriceShopify 官方說明Variant Price只填金額,不加貨幣符號,如 9.99。預設 0.00。
Compare-at priceShopify 官方說明Variant Compare At Price, Variant Compare-at Price顯示為刪除線的原價,應高於 Price。
Cost per itemShopify 官方說明—此款式的成本,只填金額。
Charge taxShopify 官方說明Variant Taxable是否對此款式收稅,預設 true。truefalse
Tax codeShopify 官方說明Variant Tax Code稅務服務使用的稅碼,不使用時留空。
Unit price total measureShopify 官方說明Unit Price Total Measure商品的總量,用於顯示單價。
Unit price total measure unitShopify 官方說明Unit Price Total Measure Unit總量的單位。
Unit price base measureShopify 官方說明Unit Price Base Measure單價的基準量,如 100。
Unit price base measure unitShopify 官方說明Unit Price Base Measure Unit基準量的單位。
Inventory trackerShopify 官方說明Variant Inventory Tracker由哪個服務追蹤庫存,不追蹤時留空。shopifyshipwireamazon_marketplace_web
Inventory quantityShopify 官方說明Variant Inventory Qty整數,只適用於單一庫存地點的商店,預設 0。
Continue selling when out of stockShopify 官方說明Variant Inventory Policy缺貨時是否允許繼續購買,預設 deny。denycontinue
Weight value (grams)Shopify 官方說明Variant Grams整數公克數,不加單位和小數。
Weight unit for displayShopify 官方說明Variant Weight Unit顯示重量時使用的單位,預設 kg。gkglboz
Requires shippingShopify 官方說明Variant Requires Shipping是否需要運送,預設 true。truefalse
Fulfillment serviceShopify 官方說明Variant Fulfillment Service預設 manual;自訂服務使用小寫字母和連字號。
Product image URLShopify 官方說明Image Src以 http:// 或 https:// 開頭的公開圖片連結,每列一張。每項商品最多 250 張圖
Image positionShopify 官方說明Image Position圖片的顯示順序,從 1 開始。
Image alt textShopify 官方說明Image Alt Text圖片的簡短描述,供螢幕閱讀器和搜尋引擎使用。最多 512 個字元
Variant image URLShopify 官方說明Variant Image選取此款式時顯示的圖片。
Gift cardShopify 官方說明Gift Card標示為禮品卡。禮品卡無法用 CSV 建立。truefalse
SEO titleShopify 官方說明SEO Title搜尋結果中顯示的標題,留空則使用商品標題。最多 70 個字元
SEO descriptionShopify 官方說明SEO Description搜尋結果中顯示的說明,留空則使用商品說明。最多 320 個字元
Packed product lengthShopify 官方說明—包裝後的長度。四個包裝尺寸欄位要嘛全填,要嘛全空。
Packed product widthShopify 官方說明—包裝後的寬度。四個包裝尺寸欄位要嘛全填,要嘛全空。
Packed product heightShopify 官方說明—包裝後的高度。四個包裝尺寸欄位要嘛全填,要嘛全空。
Packed product dimension unitShopify 官方說明—包裝尺寸的單位。cmin
CollectionShopify 官方說明—把商品加入一個商品系列,系列不存在時會自動建立。這是唯一可以額外新增的欄位。最多 255 個字元

覆寫既有商品

空白儲存格會清除資料

開啟「覆寫具有相同 handle 的商品」時,檔案中包含的欄位如果儲存格是空的,商店中對應的值會被清除。

未包含的欄位維持不變

檔案中沒有的欄位,商店中的值維持原樣。

修改選項值會重建款式

修改 Option1、Option2 或 Option3 的值會刪除現有款式 ID 並產生新的 ID,可能導致依賴這些 ID 的應用程式出錯。

Shopify 匯入錯誤對照

Shopify 錯誤訊息含義相關檢查
Ignored line #-## because handle example already exists這個 handle 又開始了一項新商品,而它在檔案前面已經出現過。PRODUCT_HANDLE_DUPLICATE
Ignored line #-## because it did not contain product data某個 handle 有若干列,但沒有一列填寫了 Title。PRODUCT_TITLE_MISSINGPRODUCT_ROW_UNASSIGNED
Illegal quoting on line檔案不是 UTF-8 編碼,或有引號位置錯誤。FILE_ENCODING_NOT_UTF8FILE_QUOTE_MALFORMED
Missing or stray quote on line缺少或多出了引號,常見原因是彎引號。FILE_QUOTE_MALFORMEDFILE_SMART_QUOTES
Invalid CSV header: missing headers缺少必要欄位,或欄位名稱拼寫錯誤。HEADER_TITLE_MISSINGHEADER_HANDLE_MISSINGHEADER_UNKNOWN
Network error: Unexpected token < in JSON at position 0欄位名稱與 Shopify 的寫法不完全一致(包括大小寫)。HEADER_CASE_MISMATCHHEADER_WHITESPACE
Inventory policy is not included in the list「缺貨時繼續銷售」不是 deny 或 continue。INVENTORY_POLICY_INVALID
Inventory quantity can't be blank有追蹤庫存,但庫存數量是空的。INVENTORY_QTY_BLANK
Inventory quantity is not a number庫存數量不是整數。INVENTORY_QTY_INVALID
Fulfillment service can't be blank出貨服務是空的。FULFILLMENT_BLANK
Validation failed: options are not unique同一項商品的兩個款式選項值完全相同。VARIANT_DUPLICATE_OPTIONS
Validation failed: price can't be blank某個款式沒有價格。PRICE_BLANK
Validation failed: getaddrinfo: nodename nor servname provided, or not known圖片網址不完整,或沒有以 http 開頭。IMAGE_URL_INVALIDIMAGE_URL_LOCAL
Not a valid product category商品類別與 Shopify 分類表不相符。PRODUCT_CATEGORY_FORMAT
Shopify 官方說明

所有檢查項目

檔案與編碼

  • 錯誤檔案是空的FILE_EMPTY

    重新從 Shopify 匯出商品,或在標題列下方至少新增一列商品。

    Shopify 官方說明
  • 錯誤檔案超過 15 MBFILE_TOO_LARGE

    把檔案拆成幾個較小的檔案,分別匯入。

    Shopify 官方說明
  • 錯誤檔案不是 UTF-8 編碼FILE_ENCODING_NOT_UTF8

    開啟檔案,另存為「CSV UTF-8」格式。Google 試算表預設就是 UTF-8。

    Shopify 官方說明
  • 錯誤檔案是 UTF-16 編碼FILE_ENCODING_UTF16

    重新另存為「CSV UTF-8(逗號分隔)」,不要選擇「Unicode 文字」。

    Shopify 官方說明
  • 錯誤欄位之間不是用逗號分隔FILE_DELIMITER_NOT_COMMA

    修改試算表軟體的匯出設定改用逗號,或從 Google 試算表匯出。

    Shopify 官方說明
  • 錯誤引號缺少或多餘FILE_QUOTE_MALFORMED

    用文字編輯器開啟這一列,刪除多餘的引號,或用半形直引號把整個值括起來。

    Shopify 官方說明
  • 錯誤值被彎引號包住FILE_SMART_QUOTES

    把彎引號換成半形直引號(")。

    Shopify 官方說明
  • 錯誤欄位數量不對FILE_ROW_FIELD_COUNT

    檢查這一列是否缺少或多出逗號。

    Shopify 官方說明
  • 提示有空白列FILE_BLANK_ROWS

    刪除空白列。它們不影響匯入,但會讓檔案更難核對。

    Shopify 官方說明

標題列

  • 錯誤缺少 Title 欄位HEADER_TITLE_MISSING

    新增 Title 欄位,並在每項商品的第一列填寫商品名稱。

    Shopify 官方說明
  • 錯誤缺少 URL handle 欄位HEADER_HANDLE_MISSING

    新增 URL handle 欄位,並在每個款式列和圖片列重複填寫所屬商品的 handle。

    Shopify 官方說明
  • 錯誤欄位名稱大小寫不對HEADER_CASE_MISMATCH

    把欄位名稱改成與官方完全一致的寫法。

    Shopify 官方說明
  • 錯誤欄位名稱含多餘空格HEADER_WHITESPACE

    刪除欄位名稱中的空格。

    Shopify 官方說明
  • 錯誤無法辨識的欄位HEADER_UNKNOWN

    刪除這個欄位,或改成官方欄位名稱。唯一可以額外新增的欄位是 Collection。

    Shopify 官方說明
  • 錯誤欄位重複HEADER_DUPLICATE

    只保留其中一個欄位,刪除其餘的。

    Shopify 官方說明
  • 錯誤新舊條碼欄位同時存在HEADER_BARCODE_CONFLICT

    只保留 Barcodes 欄位。

    Shopify 官方說明
  • 警告新舊欄位名稱混用HEADER_MIXED_FORMAT

    統一使用同一版範本的欄位名稱,建議使用新版。

    Shopify 官方說明
  • 警告有款式欄位但缺少選項欄位HEADER_OPTION_COLUMNS_MISSING

    從 Shopify 匯出的檔案中補上 Option1 name 和 Option1 value 欄位。

    Shopify 官方說明
  • 錯誤包裝尺寸欄位不完整HEADER_PACKED_PARTIAL

    四個包裝尺寸欄位要嘛全部包含,要嘛全部不包含。

    Shopify 官方說明
  • 錯誤中繼欄位名稱格式錯誤HEADER_METAFIELD_FORMAT

    使用「名稱 (product.metafields.命名空間.鍵)」或「product.metafields.命名空間.鍵」的格式。

    Shopify 官方說明
  • 提示使用舊版欄位名稱HEADER_LEGACY_FORMAT

    建議改用新版範本,以確保日後的相容性。

    Shopify 官方說明

商品

  • 錯誤商品沒有標題PRODUCT_TITLE_MISSING

    在商品第一列的 Title 欄位填寫商品名稱。

    Shopify 官方說明
  • 錯誤資料列不屬於任何商品PRODUCT_ROW_UNASSIGNED

    在這些列填寫所屬商品的 URL handle,或刪除它們。

    Shopify 官方說明
  • 錯誤商品 handle 重複PRODUCT_HANDLE_DUPLICATE

    替每項商品設定不同的 handle,或把這些列合併成一項商品。

    Shopify 官方說明
  • 錯誤handle 含有無效字元PRODUCT_HANDLE_INVALID

    只使用字母、數字和連字號。

    Shopify 官方說明
  • 警告handle 含有大寫字母PRODUCT_HANDLE_UPPERCASE

    handle 中只使用小寫字母。

    Shopify 官方說明
  • 警告商品的資料列被拆散PRODUCT_ROWS_NOT_CONTIGUOUS

    把同一項商品的所有資料列放在一起,並以有 Title 的那一列開頭。

    Shopify 官方說明
  • 警告商品資訊在不同列不一致PRODUCT_FIELD_CONFLICT

    款式列和圖片列的商品層級欄位留空,或與第一列保持一致。

    Shopify 官方說明
  • 錯誤狀態值無效PRODUCT_STATUS_INVALID

    使用 active、draft 或 archived。

    Shopify 官方說明
  • 錯誤狀態為空PRODUCT_STATUS_BLANK

    填寫 active、draft 或 archived;或刪除 Status 欄位,讓所有商品都設為 active。

    Shopify 官方說明
  • 錯誤true/false 值無效PRODUCT_BOOLEAN_INVALID

    填寫 true 或 false。

    Shopify 官方說明
  • 錯誤標籤過多PRODUCT_TAGS_TOO_MANY

    刪減標籤,讓數量不超過 250 個。

    Shopify 官方說明
  • 提示標籤含重音字元或符號PRODUCT_TAGS_CHARACTERS

    標籤中只使用字母、數字和連字號。

    Shopify 官方說明
  • 警告商品類別格式不對PRODUCT_CATEGORY_FORMAT

    使用完整類別路徑(如「Apparel & Accessories > Clothing」)或類別 ID(如「aa-1」)。

    Shopify 官方說明
  • 警告無法用 CSV 建立禮品卡PRODUCT_GIFT_CARD_CREATE

    先在 Shopify 中建立禮品卡,CSV 只用來更新它的資訊。

    Shopify 官方說明
  • 錯誤商品系列名稱過長PRODUCT_COLLECTION_TOO_LONG

    縮短商品系列名稱。

    Shopify 官方說明

選項與款式

  • 錯誤缺少選項名稱OPTION_NAME_MISSING

    在商品第一列填寫選項名稱(如 Size 或 Color)。

    Shopify 官方說明
  • 錯誤缺少選項值OPTION_VALUE_MISSING

    每個款式列都要為每個選項填寫值。

    Shopify 官方說明
  • 錯誤選項名稱重複OPTION_NAME_DUPLICATE

    替每個選項取不同的名稱。

    Shopify 官方說明
  • 錯誤略過了選項OPTION_GAP

    依序填寫選項:先 Option1,再 Option2,最後 Option3。

    Shopify 官方說明
  • 錯誤款式重複VARIANT_DUPLICATE_OPTIONS

    修改其中一個選項值,或刪除重複的資料列。

    Shopify 官方說明
  • 錯誤多個款式使用了 Default TitleVARIANT_DEFAULT_TITLE_MISUSE

    改用實際的選項名稱(如 Size),或只保留一個款式。

    Shopify 官方說明
  • 警告款式數量較多VARIANT_COUNT_HIGH

    確認每個款式都是需要的。

    Shopify 官方說明
  • 錯誤選項連結格式無效VARIANT_LINKED_TO_FORMAT

    使用 product.metafields.shopify.屬性名稱 的格式,或留空。

    Shopify 官方說明

價格

  • 錯誤價格格式無效PRICE_INVALID

    只填數字,用半形句點作小數點,不加貨幣符號,例如 24.90。

    Shopify 官方說明
  • 錯誤價格為負數PRICE_NEGATIVE

    填寫大於或等於 0 的價格。

    Shopify 官方說明
  • 警告價格為空PRICE_BLANK

    替每個款式填寫價格。

    Shopify 官方說明
  • 警告價格為 0PRICE_ZERO

    確認這項商品確實是免費的。

    Shopify 官方說明
  • 警告原價不高於售價PRICE_COMPARE_AT_NOT_HIGHER

    把原價設得比售價高,或留空。

    Shopify 官方說明
  • 錯誤成本格式無效PRICE_COST_INVALID

    只填數字,用半形句點作小數點,不加貨幣符號。

    Shopify 官方說明
  • 提示成本高於售價PRICE_COST_ABOVE_PRICE

    檢查這個款式的售價和成本。

    Shopify 官方說明
  • 錯誤市場原價缺少市場價格PRICE_MARKET_COMPARE_WITHOUT_PRICE

    替該市場設定固定價格,或刪除它的原價。

    Shopify 官方說明

庫存與出貨

  • 錯誤庫存追蹤方式無效INVENTORY_TRACKER_INVALID

    使用 shopify、shipwire、amazon_marketplace_web;不追蹤庫存時留空。

    Shopify 官方說明
  • 錯誤庫存數量不是整數INVENTORY_QTY_INVALID

    填寫整數,例如 12。

    Shopify 官方說明
  • 錯誤庫存數量為空INVENTORY_QTY_BLANK

    填寫庫存數量;如果不追蹤庫存,就清空 Inventory tracker 欄位。

    Shopify 官方說明
  • 錯誤缺貨政策無效INVENTORY_POLICY_INVALID

    使用 deny 或 continue。

    Shopify 官方說明
  • 錯誤缺貨政策為空INVENTORY_POLICY_BLANK

    填寫 deny 或 continue。

    Shopify 官方說明
  • 錯誤出貨服務為空FULFILLMENT_BLANK

    自行出貨時填寫 manual。

    Shopify 官方說明
  • 錯誤出貨服務名稱無效FULFILLMENT_FORMAT

    只使用小寫字母和連字號,例如 joans-fulfillment。

    Shopify 官方說明
  • 錯誤出貨服務需要 SKUFULFILLMENT_SKU_REQUIRED

    由自訂出貨服務處理的款式都必須填寫 SKU。

    Shopify 官方說明

運送與重量

  • 錯誤重量無效WEIGHT_INVALID

    以公克為單位填寫,不加單位和小數。例如 5.125 公斤填 5125。

    Shopify 官方說明
  • 錯誤重量單位無效WEIGHT_UNIT_INVALID

    使用 g、kg、lb 或 oz。

    Shopify 官方說明
  • 錯誤true/false 值無效SHIPPING_BOOLEAN_INVALID

    填寫 true 或 false。

    Shopify 官方說明
  • 錯誤包裝尺寸不完整PACKED_PARTIAL

    長、寬、高和單位要嘛全部填寫,要嘛全部留空。

    Shopify 官方說明
  • 錯誤包裝尺寸單位無效PACKED_UNIT_INVALID

    使用 cm 或 in。

    Shopify 官方說明
  • 錯誤包裝尺寸無效PACKED_VALUE_INVALID

    填寫大於 0 的數字。

    Shopify 官方說明
  • 提示需要運送的商品缺少重量WEIGHT_MISSING_PHYSICAL

    如果使用貨運業者計算運費或第三方出貨服務,請填寫重量。

    Shopify 官方說明

SKU 與條碼

  • 警告SKU 重複SKU_DUPLICATE

    除非刻意共用庫存,否則替每個款式設定不同的 SKU。

    Shopify 官方說明
  • 警告SKU 含多餘空格SKU_WHITESPACE

    刪除多餘的空格和換行。

    Shopify 官方說明
  • 錯誤條碼過多BARCODE_TOO_MANY

    最多保留 20 個條碼,用分號分隔。

    Shopify 官方說明
  • 警告無法辨識條碼類型BARCODE_TYPE_UNKNOWN

    使用 gtin、upc、ean、isbn 等類型;去掉前綴則以自訂條碼匯入。

    Shopify 官方說明
  • 警告條碼需要跳脫BARCODE_ESCAPE

    條碼中的反斜線寫作 \\,分號寫作 \;,冒號寫作 \:。

    Shopify 官方說明
  • 警告GTIN 檢查碼錯誤BARCODE_GTIN_CHECKSUM

    檢查條碼是否輸入錯誤。Google 購物等平台會拒絕無效的 GTIN。

    Shopify 官方說明
  • 警告條碼重複BARCODE_DUPLICATE

    每個可銷售的品項都應有自己的條碼。

    Shopify 官方說明

圖片

  • 錯誤圖片網址無效IMAGE_URL_INVALID

    使用以 https:// 開頭的公開連結。

    Shopify 官方說明
  • 提示圖片網址不是 HTTPSIMAGE_URL_NOT_HTTPS

    如果圖片主機支援,請改用 https:// 連結。

    Shopify 官方說明
  • 錯誤圖片網址不是公開網址IMAGE_URL_LOCAL

    把圖片上傳到 Shopify Files 或其他公開圖片空間,再使用那個連結。

    Shopify 官方說明
  • 警告圖片網址是縮圖IMAGE_URL_SIZE_SUFFIX

    改用原尺寸圖片的連結。

    Shopify 官方說明
  • 錯誤圖片位置無效IMAGE_POSITION_INVALID

    第一張圖填 1,第二張填 2,依此類推。

    Shopify 官方說明
  • 警告圖片位置重複IMAGE_POSITION_DUPLICATE

    同一項商品的每張圖片使用不同的位置。

    Shopify 官方說明
  • 錯誤圖片過多IMAGE_COUNT_EXCEEDED

    刪減圖片,讓數量不超過 250 張。

    Shopify 官方說明
  • 錯誤圖片替代文字過長IMAGE_ALT_TOO_LONG

    替代文字簡短描述即可,建議不超過 125 個字元。

    Shopify 官方說明
  • 提示圖片缺少替代文字IMAGE_ALT_MISSING

    加上替代文字,方便螢幕閱讀器使用者和搜尋引擎理解圖片。

    Shopify 官方說明

SEO

  • 警告SEO 標題過長SEO_TITLE_TOO_LONG

    縮短 SEO 標題,避免在搜尋結果中被截斷。

    Shopify 官方說明
  • 警告SEO 說明過長SEO_DESCRIPTION_TOO_LONG

    縮短 SEO 說明。

    Shopify 官方說明

匯入風險

  • 警告空白欄位會清除既有資料RISK_BLANK_COLUMN_CLEARS

    不打算修改這個欄位就刪除它,否則請填寫內容。

    Shopify 官方說明
  • 警告款式會被重建RISK_VARIANTS_RECREATED

    從 Shopify 匯出的檔案中補上 Option1 name 和 Option1 value 欄位。

    Shopify 官方說明
  • 警告檔案可能被排序過RISK_SORTED_FILE

    重新從 Shopify 匯出,或在匯入前恢復原本的列順序。

    Shopify 官方說明
  • 提示庫存數量只適用於單一地點RISK_INVENTORY_MULTI_LOCATION

    如果商店有多個庫存地點,請改用庫存 CSV 更新庫存。

    Shopify 官方說明