WooCommerce 商品 CSV 校验器
WooCommerce 的导入很少大声失败。SKU 已存在的行会被跳过,它不认识的列会被丢掉,而这次运行照样报告成功。这个工具告诉你这次导入实际上会做什么 —— 在你按下开始之前。
🔒 你的商品数据不会离开浏览器。
把店里已有的 SKU 加进来,预报才是真的(可选)
在 WordPress 后台:商品 → 导出,然后把 SKU 那一列粘到这里(每行一个)。纯数字的值会被当作商品 ID。不给这份清单的话,预报只能假定每一行都是新的。
WooCommerce 导入悄悄丢数据的两条路
1. 已经存在的行是被跳过,不是被更新
导入器按 ID 或 SKU 对照。更新已有商品不勾 —— 也就是默认状态 —— 时,每一个对上的行都会被跳过。汇总里把它们记为已跳过;而顶部的提示照样说导入已完成。如果你本来是想改价格,那就一个都没改。
2. 它不认识的列根本不会被导入
在字段映射界面上,凡是列名与导入器的 schema 对不上的列,都默认落到不导入。一个表头拼写错误、一列供应商自带的字段、或者较新的 GTIN 字段,结局都一样:导入成功,而那一列的数据干脆不在。
为什么要在这里查条码?
WooCommerce 加了一个原生的 GTIN/UPC/EAN/ISBN 字段,而它把你给的东西原样存下,不做任何校验。这个值随后流进 Google 购物和各家市场的 feed,并在那里被拒绝 —— 离引入它的那个 CSV 已经很远了。本校验器对这一列跑完整的 GS1 检查,包括校验位与表格损坏。
本工具执行的全部检查(40 条规则)
表头与列映射
WOO-H01 缺少 Name 列
WOO-H02 既没有 SKU 列也没有 ID 列
导入器靠 ID 或 SKU 把行对上已有商品。两列都没有,就没有任何可对照的东西 —— 于是以后每次重新导入都是新建一批重复商品,而不是更新已经在店里的那批。
修复: 加一列 SKU(推荐,它归你自己掌控),或者加一列从店里导出的 ID。
WOO-H03 这一列不是导入器认识的列
在字段映射界面上,每一个不认识的列都默认落到「不导入」。既不失败也不告警 —— 这一列就这么被丢掉了。所以一个表头拼写错误(比如 "Regular Price " 多了个空格)或者一列供应商自带的字段,数据会无声地消失。
修复: 把它改成 WooCommerce 的准确列名,或者在导入界面上手工映射(自定义字段要写成 "meta:key" 的形式)。
WOO-H04 重复的列
WOO-H05 这一行的字段数与表头不一致
某一行的字段比表头多或少,意味着有一个逗号没被引号包住,或者某个取值里夹了换行。从断开的地方起,后面每一个值都落进了错误的列 —— 价格跑到库存列,描述跑到分类列。
修复: 含逗号、引号或换行的取值用双引号包起来,取值内部的引号写成两个。
WOO-H06 重量与尺寸的表头带着店铺单位
WooCommerce 把这些列导出成 "Weight (kg)"、"Length (cm)" 这样,括号里是该店铺配置的单位。导入器不做换算:一个从公斤店导出的文件导进磅制店,数字原样不动,含义却变了。
修复: 核对表头里的单位与目标店铺是否一致(WooCommerce → 设置 → 商品),不一致就自己先换算。
WOO-H07 有 GTIN 列,但它不在默认映射里
WooCommerce 从 9.2 起有了原生的「GTIN, UPC, EAN, or ISBN」商品字段,存放在 meta 键 global_unique_id 下。但默认的 CSV 导出不含这一列,导入器也不会按这个名字自动映射 —— 所以除非你手工映射,这个文件里的条码会被丢掉。
修复: 在导入映射界面上把这一列指到 GTIN 字段(该字段没被提供的版本上写 "meta:global_unique_id"),导完之后挑一个商品核对一下。
来源: yaktool engineering note, not an official WooCommerce statement: WooCommerce 9.2 added a native "GTIN, UPC, EAN, or ISBN" product field stored as the meta key global_unique_id, but the documented default CSV columns do not include it and sellers report it missing from exports — so a barcode column needs mapping by hand. Verify against your own WooCommerce version before relying on it.
身份:新建、更新还是跳过
WOO-I01 文件内部有重复的 SKU
WooCommerce 强制 SKU 唯一。两行带着同一个 SKU 不可能都导进去:第二行会被拒绝,而哪一行活下来取决于行序,不取决于你的本意。
修复: 给每个商品各自的 SKU。变体商品的父商品与每个变体也各需要一个不同的 SKU(或者干脆都不写)。
WOO-I02 这一行带着 ID
ID 不能指派给新商品 —— 它是 WordPress 的文章 ID,由店铺自己分配。目标店里不存在的 ID 会让这一行失败,这正是「从一个店导出的文件很少能干净地导进另一个店」的原因。
修复: 在店铺之间搬商品时,删掉 ID 列,改用 SKU 对照。
WOO-I03 SKU 在店里已经存在
这是最闷声的一条。「更新已有商品」不勾 —— 也就是默认状态 —— 时,凡是 SKU 或 ID 已存在的行都会被整行跳过,而导入界面照样把这次运行报告为完成,你本想改的那些商品一个都没动。
修复: 上传之前先决定:勾上「更新已有商品」来覆盖这些行,或者把它们从文件里去掉。
WOO-I04 文件里新商品与已有商品混在一起
一次导入只对所有行套用同一种模式。所以混装的文件永远会丢掉你想要的一半:不勾就跳过了更新,勾上则新行进来了,同时也把已有商品重写了一遍。
修复: 把文件拆成「新商品」和「更新」两份,分两次导入。
WOO-I05 这一行既没有 SKU 也没有 ID
商品类型与变体
WOO-T01 未知的商品 Type
Type 接受 simple、variable、variation、grouped、external。像 "downloadable" 或 "virtual" 这样的值不是类型 —— 它们是各自独立的布尔列 —— 而一个不认识的类型会让导入器落回 simple 商品,把变体商品悄悄压平。
修复: 用 simple、variable、variation、grouped、external 之一。downloadable 与 virtual 在它们各自的列里标记。
WOO-T02 变体行没有 Parent
变体离开父商品毫无意义:没有 Parent 就没有它所属的商品,于是它作为一个孤儿导入,永远不会在店里出现。
修复: 把 Parent 填成父商品的 SKU;引用数字型商品 ID 时写作 "id:123"。
WOO-T03 数字型的 Parent 引用缺少 "id:" 前缀
Parent、Grouped products、Upsells 和 Cross-sells 接受直接写 SKU,但引用 ID 必须写成 "id:123"。一个光秃秃的数字会被当成 SKU —— 而「SKU 本身长得像数字」正是这件事出错却没人发现的那种情况。
修复: 引用 ID 写 "id:123";SKU 不加前缀。
WOO-T04 Parent 不在这个文件里
父商品必须已经在店里,或者出现在同一次导入中。两样都不占,这个变体就被丢掉,商品最后拥有的变体比文件里描述的少 —— 而且没有任何报错说这件事。
修复: 把父商品行放进同一个文件(父在变体之前),或者先导入父商品。
WOO-T05 一个变体给一个属性写了好几个值
一个变体对每个属性只钉一个值。给了好几个时,导入器取第一个、丢掉其余 —— 于是 "Red, Blue" 悄悄变成了 "Red"。
修复: 每个变体的每个属性只给一个值;完整的取值集合写在 variable 父商品那一行。
WOO-T06 属性列不成对
每个属性需要名字和取值成对出现。只有名字没有取值(或者只有取值没有名字)会被整个跳过 —— 整理表格时删掉了其中一列,常常就是这个结果。
修复: 把 "Attribute N name" 与 "Attribute N value(s)" 当成一对来维护;需要的话再加上 visibility 与 global 列。
WOO-T07 属性默认值不在该属性的取值之中
WOO-T08 variable 商品没有任何属性取值
variable 商品至少需要一个带取值的属性,才能据此生成变体。没有它,商品导入之后是个空壳,顾客没有任何选项可选。
修复: 在 variable 父商品那一行加上 "Attribute 1 name" 与 "Attribute 1 value(s)"。
字段取值
WOO-F01 Published 的值不在预期之内
Published 接受 1(已发布)、0(私密)、-1(草稿)和 2(待审核)。除此之外的东西 —— "yes"、"publish"、"TRUE" —— 正是 WooCommerce 自己列出的「行导进去了却始终不出现在站点上」的原因之一。
修复: 用 1、0、-1 或 2。
WOO-F02 布尔列的值不是 1 或 0
导入器的布尔列只吃 1 和 0。表格导出最爱写 TRUE/FALSE、"yes"/"no" 或者本地化的词,而它们统统被读成 false —— 于是推荐商品不再被推荐,评价被关掉。
修复: 换成 1 或 0。"Backorders allowed?" 额外接受 "notify"。
WOO-F03 价格不是一个纯数字
价格必须是光秃秃的数字:没有货币符号,没有千分位,也不能用逗号当小数点。"1,299.00" 会被读成 1,"€24,99" 会被读成 0 —— 两者都能顺利导入,两者都是错的。
修复: 写 1299.00 和 24.99。货币在 WooCommerce 设置里配置,不写在文件里。
WOO-F04 促销价没有低于原价
WOO-F05 日期不是 YYYY-MM-DD
促销的起止日期必须写成 YYYY-MM-DD。表格里显示为 01/09/2026 的单元格,导出时按区域设置要么日在前要么月在前 —— 于是同一个文件在两台机器上排出了两场不同的促销。
修复: 把该列设为文本格式,写 2026-09-01。不设日期就留空。
WOO-F06 促销的结束早于开始
WOO-F07 库存值不是整数
Stock 接受一个数字,而写了这个数字也就同时为该商品打开了库存管理。文本、小数或者一个多余的单位都会让这个值没法用;"parent" 只在变体行上有效,在那里它的意思是「继承父商品的库存设置」。
修复: 用整数;想让库存管理保持关闭就留空;变体行上可以用 "parent"。
WOO-F08 In stock? 与 Stock 数字互相矛盾
一行写着缺货,却带着一个正数的库存数(或者反过来),会让店铺显示的和库存记录的对不上 —— 而最终哪一个说了算,取决于库存管理是否被打开。
修复: 让两者一致,或者干脆只用 Stock 一列来管理可售状态。
WOO-F09 分类取值看着像路径,却没用文档规定的分隔符
分类之间用逗号分隔,层级用 ">" 写("Home goods > Audio"),分类名里的逗号必须用反斜杠转义。用 "/" 或 "|" 表示层级不会建出父子关系,只会建出一个名字里带斜杠的扁平分类。
修复: 写 "Parent > Child";多个分类之间用逗号分隔;字面的逗号写成 "\,"。
WOO-F10 图片取值既不是完整 URL 也不是媒体库文件名
图片之间用逗号分隔,每一项要么是服务器能直接抓取的绝对 URL,要么是媒体库里已有文件的文件名。跳转不会被跟随,所以短链接和 Dropbox 那种分享 URL 导进来等于什么都没有。
修复: 用直指图片文件本身的 https URL;第一张排在最前 —— 它会成为主图。
WOO-F11 未知的目录可见性
Visibility in catalog 接受 visible、catalog、search 和 hidden。不认识的值会悄悄落回 visible —— 本该隐藏的商品就是这样出现在店铺页上的。
修复: 用 visible、catalog、search、hidden 之一。
WOO-F12 未知的税务状态
Tax status 接受 taxable、shipping 和 none。别的值会悄悄落回 taxable —— 这是一次无声的税务变更,而不是一个导入错误。
修复: 用 taxable、shipping 或 none;想用店铺默认值就把 Tax class 留空。
WOO-F13 重量或尺寸里带着单位
WOO-F14 非 external 商品上填了 External URL 或 Button text
这两列只对 external / 联盟商品有效。填在 simple 或 variable 商品上,它们会导进去然后什么也不做 —— 这通常说明 Type 列写错了,而不是 URL 写错了。
修复: 商品确实要外链就把 Type 设成 "external",否则清空这两列。
WOO-F15 条码通不过 GS1 校验
WooCommerce 把你填进 GTIN 字段的东西原样存下,不做任何检查。这个条码随后会流进 Google 购物、Meta 和各家市场的 feed,并在那里被拒绝 —— 离引入它的那个文件已经很远了。
修复: 把这个值放进 GTIN 校验器跑一遍:校验位错、丢了前导零、被表格弄坏,都会在那里显示出来,并给出更正后的值。
来源: yaktool engineering note, not an official WooCommerce statement: WooCommerce 9.2 added a native "GTIN, UPC, EAN, or ISBN" product field stored as the meta key global_unique_id, but the documented default CSV columns do not include it and sellers report it missing from exports — so a barcode column needs mapping by hand. Verify against your own WooCommerce version before relying on it.
编码与表格损坏
WOO-E01 文件不是合法的 UTF-8
WooCommerce 要求 UTF-8。存成 Windows-1252 或 Latin-1 的文件导进来重音符号会变成乱码("Café"),而因为这些文本在技术上是合法的,导入照样报告成功。
修复: 重新另存为 CSV UTF-8。Excel 里:文件 → 另存为 → 「CSV UTF-8(逗号分隔)」。
WOO-E02 文件不是逗号分隔的
导入器默认按逗号切分。欧洲区域设置下的 Excel 导出的是分号,结果整行落进一个列里 —— 要么每个值都在错误的位置,要么映射界面上只剩一个巨大的字段。
修复: 用逗号重新导出,或者在导入界面的「高级选项」里设定分隔符。
WOO-E03 取值里有不可见字符或不换行空格
零宽字符和不换行空格能从网页和 Word 的复制粘贴里活下来。它们会让两个看上去一模一样的 SKU 对不上,也会把一个数字型的价格变成文本。
修复: 把它们清掉(不可见字符检测器能指出它们的确切位置),然后重新核对 SKU 列。
WOO-E04 标识符列里有表格损坏
科学计数法(8.71E+12)和丢掉的前导零,是表格软件对长数字编码干的事。两者都会导入成一段不再能指认该商品的文本。
修复: 粘贴之前把该列设为文本格式,或者用导入向导打开 CSV 并把标识符列标记为文本。
WOO-E05 文件较大 —— 分批导入
WooCommerce 是按服务器请求分批处理文件的,它自己的文档也把「文件大到一次请求处理不完」列为导入失败的原因之一。长描述和大量变体会让并不算多的行数变得很重。
修复: 拆成每批几百行,或者在导入前调高服务器限制。
关于这些规则。 每一条都有编号、严重级别和通俗解释。每个来源链接都已登记在案,并对线上页面实际复验过,而不是凭印象写上去的. 规则如何编写、测试与保持更新 →