使用 WooCommerce 商品 CSV 导入与导出工具

WooCommerce 内置 CSV 工具，可导入、导出和批量更新商品。它适合一次添加大量商品、在商店之间迁移商品数据，或批量修改已有商品。本指南介绍 CSV 格式、导入导出步骤以及常见故障处理。

找到导入与导出工具

打开“商品 > 所有商品”（Products > All Products），“导入”和“导出”按钮位于“添加新商品”旁边。

这些工具可用于为新商店建立商品目录，也可以更新商品详情、安排促销价格，或让多个商店的数据保持一致。

注意：如果使用付费的 Product CSV Import Suite 扩展，应遵循该扩展自身的文档。

创建 CSV 文件

推荐的 CSV 编辑器

原文推荐以下工具：

• Google Sheets
• Apache OpenOffice Calc
• LibreOffice Calc
• macOS Numbers

无论选择哪种编辑器，都应以 UTF-8 CSV 保存或导出，并遵循下文的通用规则。电子表格软件可能改变格式或字符编码，因此导入前应检查实际保存的 CSV。

准备商品 CSV

导入新商品或更新现有商品，都需要包含商品信息的 CSV。可以采用以下来源：

• 从已有商店导出商品 CSV。
• 下载 GitHub 上的示例商品 CSV，再用自己的商品数据替换示例值。
• 根据本文末尾的商品 CSV 字段结构，自行创建文件。

WooCommerce 导出的 CSV 已符合要求。如果从示例文件开始，应保留规定的列名和格式，仅替换示例数据。

通用规则

• 使用 UTF-8 编码。
• 日期使用商店的本地时区。
• 布尔值一般以 1 表示真、0 表示假。
• 单个字段内的多个值用逗号分隔；分类名本身包含逗号时，需按下文规则转义。
• 值中包含逗号时，用双引号包裹。
• 引用已有商品 ID 时，添加 id: 前缀，例如 id:100；引用 SKU 不需要前缀，例如 SKU101。
• 分类法层级之间使用 >，多个独立分类项之间使用逗号。
• Published 控制商品状态：1 为已发布，0 为私有，-1 为草稿，2 为待审核。
• 导入新商品时不能指定固定文章 ID。无论 CSV 中填写什么 ID，WooCommerce 都使用下一个可用 ID。

处理逗号

WooCommerce 将逗号视为分隔符。如果逗号属于同一个值，必须转义，才能完整导入。

例如，要导入一个名为 Places, People, Cities 的分类，应写成 Places\, People\, Cities。反斜杠告诉导入器，这些逗号是分类名称的一部分。

图片

• 图片需要预先上传，或能够从互联网访问。
• 可以使用可直接访问的外部图片 URL，WooCommerce 会把图片导入媒体库。经过重定向脚本的链接，例如某些云存储分享链接，不受支持。
• 如果图片已经在媒体库中，可以填写文件名。
• 核心 CSV 导入器不能添加、编辑或更新商品图片的替代文本。

导入商品

添加新商品

CSV 导入器允许一次上传多个商品。

1. 打开“商品 > 所有商品”。
2. 点击页面顶部的“导入”，打开“上传 CSV 文件”页面。

1. 点击“选择文件”，选中 CSV 或 TXT。也可以打开“显示高级选项”，填写服务器上已有 CSV 的文件路径。
2. 点击“继续”。只有选中本地文件或填写服务器路径后，该按钮才可用。
3. 查看“列映射”页面，WooCommerce 会把识别出的 CSV 列自动映射到商品字段。

1. 通过下拉菜单调整映射，或者为不需要的列选择“不导入”。
2. 未识别的列默认不会导入。
3. 点击“运行导入器”。
4. 等待完成。导入期间不要刷新页面或离开当前页面。

完成后，新商品即已导入。

更新已有商品

可以用 CSV 批量更新商品，例如添加品牌、改变税类、准备促销，或同步多个商店的数据。导入器通过商品 ID 或 SKU 匹配已有商品。

1. 创建 CSV，包含需要更新商品的 ID 或 SKU。
2. 打开“商品 > 所有商品”。
3. 点击“导入”。
4. 选择 CSV 文件。
5. 勾选“更新已有商品”。按 ID 或 SKU 匹配的商品会被更新，不存在的商品通常会跳过。
6. 点击“继续”，查看列映射。
7. 调整字段映射，或选择“不导入”忽略相应列。
8. 点击“运行导入器”。
9. 等待结束，不要刷新或离开页面。

注意：从 WooCommerce 11.1 起，更新导入中的变体行即使没有匹配到已有商品，也不一定会跳过。如果其 Parent 匹配已有可变商品，同时包含 SKU，或已映射的 GTIN、UPC、EAN、ISBN，并提供父商品已经具备的属性和值，WooCommerce 会将其创建为新变体。缺少任何条件的行仍会跳过。完整条件见更新可变商品时添加变体。

导入失败或部分行被跳过

导入结束后如果缺少部分商品，应先查看导入日志。常见原因包括：

• 已有相同 SKU 或 ID 的商品，但没有勾选“更新已有商品”。
• CSV 的列名或值不符合商品导入字段结构。
• Published 值导致了意料之外的商品状态，应参考下方字段表。
• 插件或主题冲突中断了导入。
• CSV 太大，服务器无法在一次请求中处理，应拆分为较小批次。

上传文件报错

某些服务器会误判包含 HTML 的 CSV 文件类型，并提示 Sorry, this file type is not permitted for security reasons.。

首先确认文件确实保存为 CSV。如果仍无法上传，可通过 SFTP 或主机文件管理器，将 CSV 放入网站的 uploads 目录，然后在导入器的“显示高级选项”中填写服务器文件路径。填写路径后，“继续”按钮会启用。

如果服务器路径方式仍失败，应请主机服务商检查允许的文件类型和上传配置。

导入大型商品目录

大型导入取决于服务器可用内存、上传大小限制和处理时间。导入前应备份，并先在预发布站点测试少量数据。将 CSV 分成小批次，更容易定位和处理问题。

上传页面显示的“最大大小”由服务器决定，需要提高时应联系主机服务商。

对于特别大规模的导入，或扩展提供的自定义商品数据，可以考虑 Product CSV Import Suite。

将简单商品转换为可变商品

可以通过 CSV 将已有简单商品转换为可变商品。自 WooCommerce 11.1 起，如果 CSV 中父商品行位于变体行之前，可一次导入完成。早期版本，或无法保证行顺序时，需要两次导入：先把已有商品改为带属性的可变商品，再将变体作为新商品导入。

开始前应备份或在预发布站点测试。准备一个已有 SKU 和价格的简单商品，并从“商品 > 所有商品”将其导出。

1. 在 CSV 编辑器中打开导出文件。
2. 保留原商品行，并为每个变体新增一行。
3. 将父商品行的 Type 从 simple 改为 variable。
4. 各变体行的 Type 设为 variation。
5. 为各变体设置独立且唯一的 SKU 与 Name。
6. 添加所需属性列。例如本地“Size”属性需要 Attribute 1 name、Attribute 1 value(s)、Attribute 1 visible、Attribute 1 global。
7. 父商品的 Attribute 1 value(s) 列出全部值，例如 S, M；变体行只填写自己的值，例如 S 或 M。
8. Attribute 1 visible 设为 1。本地属性的 Attribute 1 global 设为 0；如果使用商店已配置的全局属性，则设为 1。
9. 每个变体的 Parent 填写父商品 SKU 或 ID。

行类型	Type	SKU	Parent	Attribute 1 name	Attribute 1 value(s)	Attribute 1 visible	Attribute 1 global
父商品	variable	tshirt		Size	S, M	1	0
变体	variation	tshirt-s	tshirt	Size	S	1	0
变体	variation	tshirt-m	tshirt	Size	M	1	0

编辑后另存为新 CSV。

如果父商品行在变体行之前，且使用 WooCommerce 11.1 或更新版本，可以勾选“更新已有商品”一次导入。WooCommerce 会将原商品更新为可变商品，同时创建新变体，前提是各变体有唯一 SKU，或已映射的 GTIN、UPC、EAN、ISBN，并且 Parent 正确匹配父商品。

如果不能保证行顺序，或版本早于 11.1，则分两次导入：

1. 第一次勾选“更新已有商品”，把原商品改为可变商品并添加属性。尚不存在的变体行会被跳过。
2. 再次打开 CSV，删除父商品行，只保留变体行。
3. 导入这个仅含变体的 CSV，不勾选“更新已有商品”，从而创建变体并连接到父商品。
4. 无论使用哪种方式，完成后打开商品，确认类型和变体符合预期。

如果变体未创建，检查 SKU 是否唯一、Parent 是否匹配父商品 SKU 或形如 id:123 的 ID，以及属性列是否与父商品一致。使用单次导入时，还要确认父商品行位于变体之前。

整理供应商提供的可变商品 CSV

供应商文件的列名、标识符和属性格式，常常不同于 WooCommerce 要求。上传前应统一格式，并先导入小样本。

1. 明确是创建新商品还是更新已有商品。更新时，先导出几个已有商品，用来核对供应商文件的列名与标识符。
2. 为每个父商品选择稳定标识，例如 SKU 或商品 ID。各变体使用唯一 SKU，并在每个变体行填写同一个父商品标识。
3. 统一表头和属性值，去除首尾空格、统一大小写，并把同义写法合并。例如将 L、l、Large 统一为 Large。父商品与变体中的属性名称和值，拼写必须一致。
4. 每个父商品准备一行，Type 为 variable，填写父 SKU 或 ID，以及完整属性值集合。每个变体另设一行，Type 为 variation，填写唯一 SKU、Parent 和对应属性值。本地属性的四个属性列，在父商品与变体中应保持一致，列名采用下方字段表的准确名称。
5. 删除供应商专用列、公式、货币符号、多余空格和不受支持的格式，以 UTF-8 CSV 保存。内置导入器识别标准商品字段和 meta: 前缀元数据列。扩展专用字段应查阅扩展文档，例如 Product CSV Import Suite 的变体导入指南。
6. 备份商店，在测试或预发布站点先导入一个父商品和几个变体。查看结果，并打开父商品确认变体、属性、价格、库存与图片正确，再处理其余数据。
7. 如果工作流需要分开的父商品与变体文件，先导入或更新父商品，再导入变体。重复导入时保持 ID 或 SKU 稳定。通常勾选“更新已有商品”会更新匹配行、跳过不匹配行；不勾选则跳过已经存在的 ID 或 SKU。WooCommerce 11.1 的新变体例外条件见前文。

如果有行被跳过，或变体结构没有建立，应查看失败与跳过行报告，核对父 ID 或 SKU、变体 SKU、Type、Parent 以及属性名称和值。修正供应商文件后再导入。需要预处理的文件必须在上传前整理，不要在小样本尚未成功时反复导入完整文件。

导出商品

内置 CSV 工具可将当前商品目录导出：

1. 打开“商品 > 所有商品”。
2. 点击“导出”，进入“导出商品”页面。

1. 选择要导出的列，或保留“导出所有列”。
2. 选择商品类型和分类，或保留默认值导出全部。
3. 如果需要 WooCommerce 或其他插件保存的商品元数据，勾选“是，导出所有自定义元数据”。元数据列以 meta: 开头，例如 product_depth 导出为 meta:product_depth。
4. 点击“生成 CSV”，等待完成。

浏览器会下载生成的 CSV 文件。

导出文件中的变体名称

WooCommerce 可能不在导出的变体名称中包含属性值。以下情况属于预期行为：商品具有三个及以上属性；或者至少两个属性，而且其中至少一个属性名包含两个及以上单词。

修改这种行为需要使用 woocommerce_product_variation_title_include_attributes 过滤器编写自定义代码。这属于开发者级定制，不包含在 WooCommerce 支持政策的常规支持范围内。

只导出选中的商品

1. 打开“商品 > 所有商品”。
2. 勾选需要导出的商品。
3. 点击页面顶部的“导出所选 X 项”，按钮会显示所选数量。

商品 CSV 导入字段结构

内置导入与导出工具采用以下结构，也可查看 GitHub 上的字段规范。CSV 列名与程序字段保持原样，说明译为中文。

CSV 列名	对应商品属性	示例	说明
ID	id	100	用于识别要更新的已有商品，不能为新商品指定固定 ID。
Type	type	simple, variation, virtual	支持 simple、variable、grouped、external、variation、virtual、downloadable，多种类型用逗号分隔。
SKU	sku	woo-headphones	必填；省略时 WooCommerce 会生成一个。
Name	name	Headphones	必填。
Published	status	1	1 为发布，0 为私有，-1 为草稿，2 为待审核；也可用 true 表示发布、false 表示草稿。
Is featured?	featured	1	1 为真，0 为假。
Visibility in catalog	catalog_visibility	visible	支持 visible、catalog、search、hidden。
Short description	short_description	This is a product.	商品简短描述。
Description	description	This is more information about a product.	商品详细描述。
Date sale price starts	date_on_sale_from	2026-06-07	从指定日期开始时生效，留空表示没有开始日期。
Date sale price ends	date_on_sale_to	2026-06-14	到指定日期结束时失效，留空表示没有结束日期。
Tax status	tax_status	taxable	支持 taxable、shipping、none。
Tax class	tax_class	standard	使用已有税类的别名。
In stock?	stock_status	1	1 为真，0 为假。
Stock	manage_stock / stock_quantity	20	数值库存会启用库存管理；变体用 parent 表示继承父商品库存设置；留空禁用库存管理。
Low stock amount	low_stock_amount	3	留空或填写数值。
Backorders allowed?	backorders	1	支持 1、0 或 notify。
Sold individually?	sold_individually	1	1 为真，0 为假。
Weight (unit)	weight	100	只解析数字。
Length (unit)	length	20	只解析数字。
Width (unit)	width	20	只解析数字。
Height (unit)	height	20	只解析数字。
Allow customer reviews?	reviews_allowed	1	1 为真，0 为假。
Purchase note	purchase_note	Thanks for your order.	购买备注。
Sale price	sale_price	20.99	促销价。
Regular price	regular_price	24.99	常规价格。
Categories	category_ids	Electronics, Home goods > Audio	分类用逗号分隔，层级用 > 表示。
Tags	tag_ids	Wireless, Audio	标签用逗号分隔。
Shipping class	shipping_class_id	Standard	配送类名称。
Images	image_id / gallery_image_ids	https://example.com/headphones.jpg, https://example.com/headphones-side.jpg	第一张图片作为特色图片。
Download limit	download_limit	1	填 n/a 或下载次数上限。
Download expiry days	download_expiry	1	填 n/a 或有效天数。
Parent	parent_id	id:100, woo-headphones	变体父商品的 ID 或 SKU；ID 需加 id: 前缀；导出时尽可能使用 SKU。
Grouped products	children	id:100, id:101, woo-headphones, woo-radio	商品 ID 或 SKU 用逗号分隔；每个 ID 加 id: 前缀；导出时尽可能使用 SKU。
Upsells	upsell_ids	id:100, id:101, woo-headphones, woo-radio	加售商品 ID 或 SKU，用逗号分隔；ID 加 id: 前缀；导出时尽可能使用 SKU。
Cross-sells	cross_sell_ids	id:100, id:101, woo-headphones, woo-radio	交叉销售商品 ID 或 SKU，用逗号分隔；ID 加 id: 前缀；导出时尽可能使用 SKU。
External URL	product_url	https://example.com/products/headphones/	外部商品 URL。
Button text	button_text	Buy now	外部商品购买按钮的自定义文字。
Position	menu_order	1	菜单顺序，用于排序。
Attribute 1 name	attributes	Color	匹配已有全局属性；没有匹配时采用商品级属性。更多属性使用递增编号列。是否“用于变体”由 WooCommerce 自动设置。
Attribute 1 value(s)	attributes	Blue, Red, Green	多值用逗号分隔。变体只需要一个值；提供多个时使用第一个。
Attribute 1 default	default_attributes	Blue	可变商品的默认属性值。
Attribute 1 visible	attributes	1	1 为真，0 为假；映射页面显示为 Attribute visibility。
Attribute 1 global	attributes	1	1 为真，0 为假；映射页面显示为 Is a global attribute?。
Download 1 name	downloads	Download 1	下载文件名称。
Download 1 URL	downloads	url.zip	下载文件地址。

自定义列与元数据

内置导入器识别标准结构中的列，以及商品元数据列。未识别的列默认不导入。

要导入自定义元数据，在表头前添加 meta:。例如，自定义字段键为 product_depth，则列名使用 meta:product_depth。如果没有自动识别，可在列映射页面手动选择“作为元数据导入”（Import as meta）。

添加全新的导入字段需要编写自定义代码，属于开发者级定制，不在 WooCommerce 常规支持政策范围内。

问题与支持

本文介绍免费的 WooCommerce 核心插件，相关支持由 WordPress.org 社区论坛提供。搜索论坛通常能找到已被回答的类似问题，参与讨论需要 WordPress.org 账户。

• 扩展核心功能可浏览 WooCommerce Marketplace。
• 持续高级支持或定制开发可聘请 Woo Agency Partner。
• 自行开发集成或扩展，可查阅开发者资源。

若原文仍未提供所需信息，可以在原文页面使用反馈按钮提出意见。

原文来源：Product CSV Importer and Exporter。本文依据留存原文译为中文，代码示例按原文保留。

© WooCommerce, Inc. 2026. An Automattic invention.