如何排查 Shopify 商品 CSV 导入错误与格式问题
先备份并用小文件测试，再根据 Shopify 的报错信息核对当前 CSV 格式和商品规则。
快速排查清单：
- 下载 Shopify 当前的示例文件，核对首行表头的拼写、大小写和空格。
- 导入前备份，并先用少量、有代表性的商品做测试。
- 检查 UTF-8 编码、逗号分隔符，以及字段内逗号和引号的转义方式。
- 对照当前官方说明检查 Handle、变体选项、必填值和公开图片链接。
- 根据失败行的具体错误修复源数据；通用 CSV 检查器无法验证每家店铺的全部规则。
Shopify 拒绝商品 CSV 时，先记录报错内容和对应行号。常见原因包括文件结构、商品与变体的关系、字段值，或图片等外部资源。Shopify 的商品 CSV 常见问题说明列出常见错误及原因；格式指南解释当前文件要求。
排查前先保护商品目录
导出受影响的商品，或保存一份未经修改的原始文件。Shopify 提醒，商品 CSV 导入开始后无法取消；选择覆盖时，非必填列中的空值也可能清空已有字段。变体关系不正确还可能影响变体或图片。选择覆盖选项前，请先查看当前的商品导入说明。
用一份只包含一个问题商品及其变体的小文件复现错误，并保留原始报错、行号和上传文件。这样更容易判断是数据问题，还是电子表格导出造成的新问题。大批量导入时，如果条件允许，先在开发店铺测试少量记录。
检查 Shopify 商品 CSV 表头和文件结构
首行应使用 Shopify 当前商品 CSV 格式中的列名。直接与官方示例和字段指南对照，不要依赖论坛里的旧模板。移除表头末尾意外添加的空格，确认分隔符是逗号，并检查文件是否确实为 CSV，而不是把 .xlsx 工作簿改名成 .csv。
Shopify 的错误说明指出，表头不匹配可能导致 “Network error: Unexpected token…” 等提示。当前文档针对这类报错说明表头大小写需要匹配。旧模板的字段名可能仍兼容，因此应先比较店铺导出的版本和当前说明，再决定是否改名，而不是盲目替换所有字段。
还要检查分隔符和换行设置。部分电子表格会根据地区设置使用分号。可以用文本编辑器确认分隔符；字段本身含逗号时，不要手工按逗号拆行，应使用理解 CSV 引号规则的编辑器正确导入和导出。
修复编码与引号问题
Shopify 商品 CSV 需要 UTF-8 编码。若重音字符、符号或中文变成乱码，请用正确编码重新打开原文件，再另存为 UTF-8。Shopify 的 CSV 文件说明介绍了编码要求。
遇到 “illegal quoting”“missing or stray quote” 或行被拆坏时，检查包含逗号、直引号、撇号和换行的字段。字段内的逗号应按 CSV 规则放入引号中；被引号包围的字段若含直双引号，通常需要将其写成两个双引号。智能弯引号是不同字符，解析器可能会拒绝。不要对整份文件做全局替换，因为商品文案中的引号可能是有效内容；请用 CSV 工具修复具体字段并重新导出测试文件。
校验 Handle、变体和关联字段
Handle 用于标识商品分组。检查是否为空、重复或末尾带空格，以及变体行是否关联到正确商品。Shopify 的常见错误包括 Handle 重复、商品行缺少标题、变体选项不唯一。
变体字段之间存在依赖。修改 SKU、重量等变体信息时，需要一并提供对应变体所需的选项名称和值。Shopify 提醒，遗漏选项列可能创建默认变体或移除已有变体；修改选项值也可能替换变体 ID，影响依赖这些 ID 的系统。导入前应确认当前字段格式和覆盖意图。
库存字段也要保持一致，例如库存追踪开关、数量和缺货策略。错误说明指出，已启用追踪的库存数量不能留空或填写非数字，库存策略也必须使用受支持的值。多地点库存有独立的 CSV 流程，请查看 Shopify 的库存 CSV 说明，不要假定商品 CSV 会更新所有地点。
检查图片与商品类别
商品图片 URL 必须能公开访问。检查协议是否缺失、文件是否需要登录、链接是否拼错或过期，以及图片是否已被删除。可在无痕窗口打开链接，确认返回的是图片而不是登录页面。Shopify 的错误说明将无效 URL 和图片下载失败列为常见导入问题。
商品类别应与 Shopify 当前的 Standard Product Taxonomy 标识符或层级路径一致。文字相似不代表类别值一定有效。自定义元字段或商品引用还需要核对命名空间、键值，以及被引用的商品是否已经存在。
谨慎重新导入
定位问题后，保存修正副本并复查行级修改，先测试小文件。若会覆盖现有商品，尤其要检查空白可选列和变体选项字段。测试成功后，再查看商品页、变体、图片、价格、目标地点库存以及关联应用的行为。确认无误前保留干净备份。
CSV 检查器能发现格式问题，但 Shopify 仍会根据店铺数据和设置验证实际导入。导入完成后，可以用多 SKU 利润体检器检查另一种受支持的 SKU 经营数据 CSV；它不负责校验商品导入文件。
常见问题
Shopify 为什么提示 CSV 表头无效？
将首行与当前 Shopify 商品 CSV 格式和示例比较。检查列名、大小写、尾随空格、分隔符设置，以及文件是否真正以逗号分隔格式导出。
商品 CSV 中的非法引号怎么修复？
找到包含逗号、双引号或换行的字段，用 CSV 编辑器按规则重新转义，再导出一个小文件验证。不要对整个文件盲目删除引号。
商品 CSV 能更新多个库存地点吗？
不要假定商品 CSV 会更新多地点库存。请使用 Shopify 为库存地点提供的专用 CSV 流程，并核对地点与数量字段。
商品 CSV 导入可以撤销吗？
Shopify 说明导入开始后无法取消。覆盖前先备份并小批量测试；如需恢复，通常要用备份文件和店铺记录人工修复。