variant-matrix

变体矩阵

概述

商品变体可让一个商品列表涵盖所有尺寸／颜色／材质组合，并为每种组合分别设置价格、SKU 和库存。平台会根据你的选项值生成完整的组合矩阵，并自动处理变体选择器 UI。主要任务包括：正确填写选项、生成所有 SKU、设置每种变体的价格和库存，以及高效管理大型矩阵。

何时使用此技能

• 为服装、鞋类或配饰建模，且商品有多个选项维度时
• 从供应商 CSV 导入商品，且需要将平铺的变体行分组时
• 为商家构建用于管理变体价格和库存的管理界面时
• 商品页面上的变体选择器需要禁用不可用的组合时

核心说明

第 1 步：确定平台并了解变体模型

平台	选项	最大变体数	变体字段
Shopify	最多 3 个选项（例如：尺寸、颜色、款式）	每件商品 100 个	价格、SKU、条形码、库存、重量、图片
WooCommerce	可使用任意数量的属性作为变体	实际上不受限制（约 50 个以上时性能会下降）	价格、促销价、SKU、库存、重量、尺寸、图片
BigCommerce	每件商品的选项数量不限	每件商品 600 个 SKU	价格调整、SKU、库存、重量、图片
自定义／无头架构	自行设计	不限	自行设计变体字段

---

第 2 步：按平台设置变体

---

Shopify

根据选项创建变体：

1. 前往 管理后台 → 商品 → [商品]
2. 滚动到 选项 部分
3. 点击 添加选项，添加第一个维度（例如：尺寸）
4. 输入选项值：XS、S、M、L、XL
5. 添加第二个选项（例如：颜色）：红色、蓝色、黑色
6. Shopify 会自动生成所有组合（5 × 3 = 15 个变体）
7. 滚动到 变体 部分，查看生成的矩阵

设置每种变体的详细信息：

• 点击任一变体行，编辑其价格、SKU、库存、重量和图片
• 或使用 编辑变体 批量视图，一次更新多个变体

批量管理变体：

• 使用复选框选择多个变体 → 点击 编辑，为一组变体更新价格或库存
• 对于大型目录：使用 Matrixify（应用商店）导入 CSV，每行对应一个变体，这是设置大型矩阵最高效的方式

禁用不可用的组合：

• 没有库存的变体会在商品页面上自动显示“已售罄”
• Shopify 的变体选择器默认不会自动禁用不可用的组合——大多数主题需要添加逻辑或使用主题应用，将售罄选项显示为灰色

发布后添加／移除选项值：

• 添加新尺码（例如“XXL”）：前往“选项”部分并添加该值
• Shopify 会为新值添加变体；现有变体不受影响
• 对停产变体进行归档，而不是删除——删除会移除订单历史记录的链接

---

WooCommerce

根据属性创建变体：

1. 创建全局属性：Products → Attributes → Add Attribute（例如，包含 XS、S、M、L、XL 的 Size）
2. 在商品中，前往 Attributes 选项卡
3. 选择属性（Size），勾选 Used for variations，然后点击 Add
4. 添加此商品使用的所有属性值
5. 前往 Variations 选项卡
6. 点击 Generate variations → WooCommerce 会为每种组合创建一个变体
7. 展开每个变体，设置价格、SKU、库存和图片

批量更新变体：

• 对于拥有 20 个以上变体的商品，WooCommerce 的变体编辑器可能会很慢
• 使用 WP All Import Pro，通过 CSV 导入大型变体矩阵
• 或使用 Variable Product Bulk Edit 插件，批量更新价格和库存

生成 SKU： WooCommerce 不会自动生成 SKU。请手动输入，或使用以下格式：

• 命名规范：[PRODUCT-CODE]-[SIZE]-[COLOR] → 例如，SHIRT-M-RED
• 使用 WP All Import 从电子表格中批量设置 SKU

---

BigCommerce

创建选项和变体：

1. 前往 Products → [Product] → Variations 选项卡
2. 点击 Create options，添加选项集（Size、Color 等）
3. BigCommerce 会自动生成 SKU 矩阵
4. 点击任意 SKU 行以设置：
   • 价格调整（例如，XL 加 $5）
   • SKU 代码
   • 库存数量
   • 图片

选项集：

• 前往 Products → Option Sets 创建可重复使用的选项组
• 创建一个包含 XS–3XL 的 “Clothing Sizes” 选项集，然后将其分配给所有服装商品
• 管理大型商品目录时可显著节省时间

批量管理 SKU：

• 前往 Products → Import & Export，导出包含所有变体 SKU 的商品目录
• 在 Excel 中编辑，然后重新导入，以批量更新价格、库存和 SKU

---

自定义／无头

根据选项的笛卡尔积生成变体，并使用差异逻辑安全地更新现有商品目录：

// lib/variantMatrix.ts

// Generate all variant combinations from option value arrays
// Input:  [['S','M','L'], ['Red','Blue']]
// Output: [['S','Red'], ['S','Blue'], ['M','Red'], ['M','Blue'], ['L','Red'], ['L','Blue']]
export function cartesianProduct(arrays: string[][]): string[][] {
  return arrays.reduce(
    (acc, values) => acc.flatMap(combo => values.map(v => [...combo, v])),
    [[]] as string[][]
  );
}

// Generate variant records with auto-generated SKUs
export function generateVariants(baseSku: string, optionNames: string[], optionValues: string[][]) {
  const combinations = cartesianProduct(optionValues);
  return combinations.map(combo => ({
    sku: [baseSku, ...combo].join('-').toUpperCase().replace(/\s+/g, '-'),
    options: Object.fromEntries(optionNames.map((name, i) => [name, combo[i]])),
    price: null,       // Set individually or via bulk rule
    inventoryQuantity: 0,
    published: true,
  }));
}

// Compute what to create vs. archive when option values change
export function diffVariants(
  existingVariants: { options: Record<string, string> }[],
  newCombinations: string[][],
  optionNames: string[]
) {
  const existingKeys = new Set(existingVariants.map(v => optionNames.map(n => v.options[n]).join('|')));
  const newKeys = new Set(newCombinations.map(c => c.join('|')));

  const toCreate = newCombinations.filter(combo => !existingKeys.has(combo.join('|')));
  const toArchive = existingVariants.filter(v => !newKeys.has(optionNames.map(n => v.options[n]).join('|')));

  return { toCreate, toArchive };
}

// Variant selector logic — which values are available given current selections?
export function getAvailableOptionValues(
  variants: { options: Record<string, string>; inventoryQuantity: number }[],
  currentSelections: Record<string, string>,
  targetOptionName: string
): string[] {
  return variants
    .filter(v =>
      Object.entries(currentSelections)
        .filter(([name]) => name !== targetOptionName)
        .every(([name, value]) => v.options[name] === value)
      && v.inventoryQuantity > 0
    )
    .map(v => v.options[targetOptionName])
    .filter(Boolean);
}

---

第 3 步：定义 SKU 命名规范

统一的 SKU 对仓库运营、报告和供应商沟通至关重要。导入商品前，请先确定命名格式。

推荐格式：

[PRODUCT-CODE]-[OPTION1]-[OPTION2]

Rules:
- Max 20 characters total
- All uppercase
- Hyphens between segments, no spaces
- Use standard size abbreviations: XS, S, M, L, XL, 2XL
- Use 3-letter color codes: RED, BLU, BLK, WHT, NVY, GRN
- Example: SHIRT-M-BLU → Blue shirt, Medium
           SHOE-10-NVY → Navy shoe, Size 10

使用 Matrixify（Shopify）或 WP All Import（WooCommerce），按照此格式为现有商品目录批量分配 SKU。

---

第 4 步：管理大型变体矩阵

对于组合较多的商品（50 个以上变体）：

Shopify： 对于包含 3 个以上选项的商品，100 个变体的上限可能会成为问题。可采用以下策略：

• 将两个选项合并为一个（例如，使用 “Size/Width”，而不是分别设置 Size 和 Width）
• 为每种颜色创建单独的商品记录，并使用 metafields 将它们关联起来
• 对于需要更高灵活性的可配置商品，使用 Shopify 原生 Bundles

WooCommerce： 单个商品的变体超过 50 个时，性能会下降。使用 WooCommerce Performance Optimizations 或 YITH WooCommerce Variations Table 改善管理后台和店面体验。

按需创建变体： 对于规模极大的矩阵（例如，自定义涂料颜色 × 表面处理 × 尺寸 = 500 个以上 SKU），可在首次下单时按需生成变体，而不是预先创建所有组合：

// For very large matrices: create variants on first request rather than upfront
export async function ensureVariantExists(productId: string, options: Record<string, string>) {
  const key = Object.values(options).join('|');
  const existing = await db.productVariants.findFirst({ where: { productId, variantKey: key } });
  if (existing) return existing;

  const product = await db.products.findUnique({ where: { id: productId } });
  return db.productVariants.create({
    data: {
      productId,
      sku: generateSku(product.baseSku, options),
      variantKey: key,
      options,
      price: applyPricingRules(product, options),
      inventoryQuantity: 0,
    },
  });
}

最佳实践

• 归档变体，不要删除 — 删除变体会导致引用它们的历史订单出错；停用时将其标记为 published: false
• 使用平台的批量编辑工具更新价格和库存 — 逐个编辑 100 个变体并不现实；所有平台都支持批量编辑
• 将选项限制在 2–3 个维度 — 超过 3 个选项（例如，尺寸 × 颜色 × 材质）会让变体选择器变得混乱，并使矩阵呈指数级增长
• 上线前测试变体选择器 — 确认选择不可用的组合时会显示正确的“售罄”状态，并且价格和图片会正确更新
• 批量导入前验证 SKU 的唯一性 — 导入时发生 SKU 冲突，根据平台不同，系统可能会静默跳过冲突行或报错

常见问题

问题	解决方案
已达到 Shopify 的 100 个变体上限	合并选项，或按颜色创建单独的商品；使用元字段在店面中关联相关商品
选择选项时变体图片没有切换	为每个变体明确分配专属图片；只有变体设有自己的图片时，平台才能切换图片
添加新的选项值会创建重复变体	使用差异逻辑检测哪些组合确实是新的；Shopify 会在管理后台正确处理，但自定义导入需要去重
大型矩阵会拖慢商品页面加载速度	对于 100 个以上的变体，在选项更改时通过 API 获取变体可用性，而不是在初始页面 HTML 中嵌入所有变体
批量导入时 SKU 冲突	生成前规范化 SKU 片段：toUpperCase().replace(/[^A-Z0-9]/g, '-')；保存前检查重复项

相关技能

• @product-data-modeling
• @inventory-tracking
• @catalog-import-export