catalog-import-export

目录导入 / 导出

概览

批量导入和导出商品是目录管理的核心任务，无论是根据供应商的电子表格为新商店导入商品、批量更新价格，还是向 Google Merchant Center 提供商品数据。各大平台都提供原生导入 / 导出工具，无需编写自定义代码即可完成这些工作。请优先使用这些工具；只有在商品数量、格式或验证要求超出平台功能范围时，才构建自定义流程。

何时使用此技能

• 为目录存放在电子表格或 ERP 系统中的新商家导入商品时
• 按计划同步供应商或 PIM 中的商品数据时
• 商家需要在不编写代码的情况下批量更新价格或库存时
• 为 Google Merchant Center、Amazon 或比价购物引擎构建商品 Feed 导出时

核心说明

第 1 步：确定平台并选择合适的导入工具

平台	推荐工具	原因
Shopify	Matrixify（Bulk Product Import Export）	可处理包含元字段、变体、多张图片和系列的复杂目录；支持计划同步和错误报告
Shopify（简单场景）	Shopify 内置的 CSV 导入工具	免费，适用于仅包含标准字段、商品数量少于几百件的基础目录
WooCommerce	WP All Import Pro	功能最强大的 WooCommerce 导入工具；支持 CSV / XML、字段映射、计划导入和条件逻辑
WooCommerce（内置）	WooCommerce Product CSV Importer	随 WooCommerce 提供；可满足简单场景下的商品、变体和图片导入需求
BigCommerce	内置批量导入 / Feedonomics	BigCommerce 的原生导入工具可满足大多数需求；Feedonomics 适用于多渠道 Feed 管理
自定义 / Headless	构建自定义流程	仅当平台没有原生工具，或验证 / 转换要求过于复杂时使用

---

第 2 步：准备导入文件

无论使用哪个平台，商品导入文件的结构都大同小异。请使用平台提供的示例 CSV 作为模板：

• Shopify：从 商品 → 导入 → 下载示例 CSV 下载示例 CSV
• WooCommerce：从 商品 → 导入 → 下载示例 CSV 下载
• BigCommerce：从 商品 → 导入和导出 → 下载模板 下载

几乎所有平台都要求提供以下关键字段：

字段	备注
Handle / Slug	URL 安全的唯一标识符（例如，blue-cotton-tshirt）
标题	商品名称
价格	小数，例如，29.99
SKU	每个变体都必须唯一
库存数量	整数
图片	逗号分隔的 URL，或单独上传
变体选项	尺寸、颜色等

重要格式规则：

• 将 CSV 文件保存为 UTF-8 编码（在 Excel 中：另存为 → CSV UTF-8）
• 使用平台示例模板中的准确列标题
• 日期采用 ISO 格式：2026-03-12
• 布尔值：true / false（不要使用 yes / no 或 1 / 0，除非平台另有规定）

---

第 3 步：平台专属设置

---

Shopify

选项 A：内置 CSV 导入（适用于简单目录）

1. 前往 Admin → Products → Import
2. 下载示例 CSV 并将其用作模板
3. 严格按照 Shopify 的列格式准备文件
4. 上传 CSV，然后点击 Import products
5. Shopify 会显示将要创建或更新内容的摘要；请在确认前仔细查看

限制：内置导入工具不支持元字段、自定义集合或复杂的变体逻辑。

选项 B：Matrixify（复杂目录推荐）

1. 从 Shopify App Store 安装 Matrixify
2. 在 Matrixify 中，点击 Export，下载当前目录作为参考表格
3. 使用导出的格式准备导入文件——其中包含所有受支持的列及示例
4. 上传文件，然后点击 Import
5. Matrixify 会显示逐行错误报告——下载报告并修复错误后再重新运行
6. 如需定时同步：前往 Matrixify → Schedules → Add schedule，设置频率（每小时、每天等），并指定 Google Sheets URL 或 FTP 路径

导出到 Google Merchant Center：

1. 在 Matrixify 中，前往 Export
2. 选择 Google Shopping 作为导出模板
3. 下载 feed XML 并上传到 Google Merchant Center，或使用 Matrixify 的直接 Google Sheets 同步功能

---

WooCommerce

选项 A：内置产品导入工具

1. 前往 WooCommerce → Products → Import
2. 上传 CSV 文件
3. 在列映射页面，将 CSV 列与 WooCommerce 字段匹配
4. 点击 Run the importer——WooCommerce 会显示进度条和摘要

选项 B：WP All Import Pro（适用于高级需求，推荐）

1. 安装 WP All Import Pro 和 WooCommerce Add-On
2. 前往 All Import → New Import
3. 上传 CSV 或 XML 文件，或输入 URL 以安排定时导入
4. 使用拖放式字段映射器，将文件中的列关联到 WooCommerce 产品字段
5. 设置 Scheduling：All Import → Manage Imports → Edit → Run automatically every X hours
6. 在 All Import → History 中查看导入日志——错误会列出对应的行号

导出到 Google Merchant Center feed：

• 安装 Product Feed Pro for WooCommerce（免费）
• 前往 Product Feed Pro → Manage Feeds → Add Feed
• 选择 Google Shopping 作为模板
• 配置并将 feed URL 直接发布到 Google Merchant Center

---

BigCommerce

内置批量导入：

1. 前往 Products → Import & Export → Import Products
2. 下载 CSV 模板
3. 准备并上传文件
4. BigCommerce 会验证文件，并在提交前显示预览
5. 对于图片：将图片托管在可访问的 URL 上，并将其填入 Product Image URL 列

Google Shopping feed：

• 前往 Channel Manager → Google Shopping
• BigCommerce 原生集成了 Google Shopping——连接 Google Merchant Center 账号后，BigCommerce 会自动同步目录

用于高级多渠道 feed： 从 BigCommerce App Marketplace 安装 Feedonomics 或 GoDataFeed，以生成 Amazon、eBay 和比价引擎 feed。

---

Custom / Headless

对于无头店面，请构建一个用于验证、转换和新增或更新产品的管道：

// lib/catalogImport.ts
import { z } from 'zod';
import { parse } from 'csv-parse';
import { createReadStream } from 'fs';

// Define and validate the import schema
const productRowSchema = z.object({
  handle: z.string().min(1).regex(/^[a-z0-9-]+$/, 'Handle must be lowercase alphanumeric with hyphens'),
  title: z.string().min(1).max(255),
  price: z.coerce.number().positive(),
  sku: z.string().min(1),
  inventory_quantity: z.coerce.number().int().min(0).default(0),
  image_url: z.string().url().optional(),
});

// Stream-parse large CSV files without loading into memory
export async function* parseCatalogCsv(filePath: string) {
  const parser = createReadStream(filePath).pipe(
    parse({ columns: true, skip_empty_lines: true, trim: true })
  );
  let rowIndex = 2;
  for await (const rawRow of parser) {
    const result = productRowSchema.safeParse(rawRow);
    yield result.success
      ? { row: rowIndex, data: result.data, errors: null }
      : { row: rowIndex, data: null, errors: result.error.issues.map(i => ({ field: i.path.join('.'), message: i.message })) };
    rowIndex++;
  }
}

// Process as an async job with upsert logic (idempotent, safe to re-run)
export async function runCatalogImport(filePath: string) {
  let processed = 0;
  const errors: { row: number; errors: { field: string; message: string }[] }[] = [];

  for await (const { row, data, errors: rowErrors } of parseCatalogCsv(filePath)) {
    if (rowErrors) { errors.push({ row, errors: rowErrors }); continue; }
    // Upsert by handle — re-running the same file won't create duplicates
    await db.products.upsert({ where: { handle: data!.handle }, create: data!, update: data! });
    processed++;
  }

  return { processed, errorCount: errors.length, errors: errors.slice(0, 50) };
}

用于导出 Google Merchant Center XML：

import { create } from 'xmlbuilder2';

export async function exportGoogleFeed(products: Product[]) {
  const root = create({ version: '1.0', encoding: 'UTF-8' })
    .ele('rss', { version: '2.0', 'xmlns:g': 'http://base.google.com/ns/1.0' })
    .ele('channel');

  for (const product of products) {
    const item = root.ele('item');
    item.ele('g:id').txt(product.sku);
    item.ele('g:title').txt(product.title);
    item.ele('g:price').txt(`${product.price} USD`);
    item.ele('g:availability').txt(product.inStock ? 'in_stock' : 'out_of_stock');
    item.ele('g:link').txt(`https://yourstore.com/products/${product.handle}`);
    item.ele('g:image_link').txt(product.images[0]);
  }

  return root.end({ prettyPrint: true });
}

---

第 4 步：提交前进行验证

所有平台都支持预览或试运行步骤——大量导入前务必使用：

• Shopify 内置工具：点击 Import 前，检查“将创建 X 个产品 / 将更新 X 个产品”的摘要
• Matrixify：导入预览会显示哪些行存在错误，以及具体的列和问题
• WP All Import：使用“Dry Run”模式预览将要创建或更新的内容
• BigCommerce：上传验证步骤会在处理前显示错误

继续操作前，请修复验证步骤中列出的所有错误。部分导入——即部分行成功、部分行失败——比修正整个文件后重新运行更难清理。

---

步骤 5：监控并验证

导入后：

1. 在管理后台随机抽查 5–10 个产品，验证标题、价格、图片和变体是否正确加载
2. 检查错误日志——Matrixify 和 WP All Import 会生成可下载的错误报告，并标注行号
3. 验证库存数量——如果导入中包含库存，请确认数量符合预期
4. 在店面测试——搜索并打开 2–3 个已导入的产品，验证其显示是否正常

最佳实践

• 始终使用平台提供的示例 CSV 作为起始模板——从头手动制作 CSV 几乎总会导致表头不匹配
• 大型目录分批导入，每批 500–1000 个产品——这样更容易排查错误，平台 UI 也能保持响应
• 大型导入前备份当前目录——先导出现有目录，以便出现问题时恢复
• 如果另有库存同步在运行，请勿通过产品导入更新库存——两个系统同时更新同一字段会产生冲突
• 使用 handle/slug 作为稳定的唯一键，而不是标题——产品标题会变，handle 不应改变
• 将定期导入安排在非高峰时段——大型同步可能会在业务高峰时拖慢管理界面

常见问题

问题	解决方案
CSV 导入因编码错误而失败	确保文件以 UTF-8 格式保存（在 Excel 中：文件 → 另存为 → CSV UTF-8）；产品名称中的特殊字符是最常见的原因
导入后图片没有显示	导入时，图片必须托管在可公开访问的 HTTPS URL 上；Shopify 和 WooCommerce 会在导入过程中下载图片
未正确创建变体	确保 CSV 中每个变体占一行（而不是每个产品占一行）；Shopify 的 CSV 格式会为多个变体重复使用 handle 行
重新运行导入时创建了重复产品	使用支持按 handle/SKU 执行 upsert 的工具（Matrixify、WP All Import）；避免使用仅支持插入的工具
产品导入后库存被重置为 0	如果库存单独管理，请勿将库存放入产品导入 CSV；大多数平台都允许跳过库存列
Google 商品源被 Merchant Center 拒绝	验证必填字段：id、title、description、link、image_link、availability、price、brand、gtin 或 mpn

相关技能

• @variant-matrix
• @product-data-modeling
• @multi-warehouse
• @product-content-enrichment