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 Shopping 等平台会拒绝无效的 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 官方说明