Shopify 商品 CSV 格式要求
整理自 Shopify 官方对商品 CSV 的要求,并列出本校验器对每条要求做的检查。最近一次与 Shopify 帮助中心核对的日期为 2026年10月29日,以 Shopify 官方最新内容为准。
文件格式
保存为 UTF-8
Shopify 只读取 UTF-8 编码的文件。其他编码会让带重音的字母、弯引号和中文等字符变成乱码,或导致 “Illegal quoting” 报错。
不要对文件排序
在表格软件中排序可能让变体和图片与所属商品分离。导入排序过的文件可能用错误数据覆盖商品,且无法恢复。
表头与必需列
表头区分大小写
列名要与 Shopify 的写法完全一致,例如 Handle 可以,handle 不行。多余的空格也会导致报错。
新旧列名
Shopify 仍然接受旧版模板的列名(如 Variant Price),但建议使用当前的列名(如 Price)。
必需列
新建商品只需要 Title;有变体的商品以及更新已有商品,还需要 URL handle。
变体数据需要选项列
如果包含 SKU、重量等变体列,也要包含 Option1 name 和 Option1 value,否则现有变体会被删除,并新建一个默认变体。
Barcode 和 Barcodes 只能二选一
文件中不能同时有旧版 Barcode 列和新版 Barcodes 列,否则会导入失败。
元字段列与市场列
元字段列使用“名称 (product.metafields.命名空间.键)”的格式;市场列使用“Price / 市场名”“Compare-at price / 市场名”和“Included / 市场名”。
行结构
| 行类型 | URL handle | Title | Option1 name | Option1 value | SKU | Price | Product image URL | Image position |
|---|---|---|---|---|---|---|---|---|
| 商品 | linen-shirt | Linen shirt | Size | S | LS-S | 39.00 | https://…/front.jpg | 1 |
| 变体 | linen-shirt | M | LS-M | 39.00 | ||||
| 图片 | linen-shirt | https://…/back.jpg | 2 |
后续行:变体
每个额外的变体占一行,填写相同的 URL handle;这些行的 Title、Description、Vendor、Tags 留空。
一个 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 个字符 |
覆盖已有商品
修改选项值会重建变体
修改 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 |
全部检查项
文件与编码
- 错误文件为空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 官方说明 - 提示变体图片不在商品图片中IMAGE_VARIANT_NOT_IN_GALLERY
变体图片使用商品图片中已有的链接。
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 官方说明