将变体图库引入核心

壳壳虫

2026.06.21

丙午马年五月初七

11 次浏览

新闻资讯

WooCommerce¹ 核心又要加新功能了。之前靠 Additional Variation Images 扩展才能做的事，现在直接合并进核心，免费开箱即用。

从 WooCommerce 10.9 开始，可变产品里的每个变体，除了原本那张特色图像，还能拥有自己有序的图像图库。

这步动作紧跟着 9.4 版本合并品牌功能，是“更多功能进核心”计划的一部分——把基础商务功能塞进核心，商家默认就能用，开发者专心做差异化。

包含哪些内容？

变体图库让每个变体都能在前台展示自己的图像。购物者选某个变体时，图库会切换显示该变体的完整图像集。

管理后台用一个统一字段集中管理每个变体的图像：变体的特色图像和图库以有序列表呈现，列表第一项自动提升为”主要”图像。

启用该功能

WooCommerce 10.9 加入了此功能，但初始阶段对所有用户默认禁用。

要在商店里启用变体图库，勾选 设置 → 高级 → 功能 里的 “变体图库” 复选框就行。

或者用编程方式，跑这条 WP-CLI⁴ 命令：

wp option update wc_feature_woocommerce_additional_variation_images_enabled 'yes'

启用后，独立的 Additional Variation Images 扩展会自动停用，避免两种实现方式打架。

功能分阶段推出，留足时间测试、收集反馈、完成迁移，逐步淘汰现有的 Additional Variation Images 订阅：

10.9 版本提供功能供用户选择测试，
后续版本通过数据库更新程序，为选定商店开启 5% 的金丝雀测试，
金丝雀测试通过后，全面启用至 100%。

首次实现的重点关注

首次实现的范围刻意控制得清晰明确：优先处理那些后期难改、容易出错的部分。

清晰的迁移路径。 当前跑着 Additional Variation Images 扩展的商店，不用手动干预就能迁移到核心。想退回扩展，数据也不会丢。向后兼容。 旧元数据留在磁盘上，运行时回退机制能确保未迁移的变体正确渲染，受影响模板的主题覆盖也能继续工作。与扩展功能对等。 AVI⁶ 插件能做的事，核心实现都能做。开箱即用的 REST API² 支持。 跟最初发布时没有 REST 端点的品牌合并不同，变体图库从第一天起就通过 REST API 暴露（详情见下文）。

所以，管理后台 UI⁷ 的首次实现可能还有点粗糙。我们选择先交付实质性的底层架构，在推出过程中迭代优化 UI，而不是因为重新设计而阻碍合并。

随着功能在金丝雀测试阶段推进，变体图库编辑器会迎来后续改进。

技术实现

变体图库存在 _product_image_gallery 里——这是 WooCommerce 已经用于父级产品图库的同一个 postmeta 键。

我们努力确保图库从第一天起就通过 REST API 暴露。变体端点的 gallery_image_ids 属性里能找到它们，结构跟父级产品用的相同。

经典前台路径和基于区块的产品图库，内部都在用这个数据负载。

对于当前使用 Additional Variation Images 扩展的站点，存在 _wc_additional_variation_images 里的旧数据，会在推出时迁移到规范位置。

旧元数据有意留在磁盘上，任何直接读它的第三方代码都能继续工作。

迁移指南

当前用着 Additional Variation Images 扩展的站点，过渡路径很平滑：启用功能后，WooCommerce 在后台安排一个 Action⁵ Scheduler 任务，把旧图库数据复制到规范位置，每次跑 250 个变体，完成后自动重新排队，直到全部完成。

迁移是幂等的，对已迁移的变体重新跑不会产生任何效果，因为有哨兵元数据兜底。不过，建议先在测试站点上试试。

跟 _wc_additional_variation_images 直接交互的自定义代码应该能继续工作，因为旧元数据保留了。但任何向变体的 _product_image_gallery 写数据的代码，可能需要意识到核心现在会从里面读数据。

前台兼容性

变体图库支持经典的单产品模板和基于区块的产品图库，能搭配多种不同组合，包括新旧区块。

支持对 single-product/add-to-cart/variable.php 的主题覆盖。

淘汰独立扩展

独立的 Additional Variation Images 扩展会在功能达到 100% 全面推出后，从 WooCommerce 市场淘汰，策略跟淘汰品牌扩展时一样。

具体来说：

当前已订阅的商家不用做任何操作。 扩展持续工作，直到商店启用核心功能。那时 WooCommerce 会自动停用独立插件防止冲突。变体图库数据继续渲染：数据一样，只是现在由核心提供服务。活跃订阅会被取消，当扩展从市场淘汰时。受影响的客户可以向支持团队申请退款或信用额度。完整细节会在淘汰邮件里发。受影响的商家会收到邮件通知，在关键推出里程碑（金丝雀测试和 100% 全面推出）时，包含说明和文档链接。文档正在迁移到核心。 现有的 Additional Variation Images 文档会被重定向到核心产品文档下的新变体图库文档。

接近 100% 全面推出时，会通过单独通知发布更多细节——包括确切的淘汰日期、订阅处理细节和文档迁移。

如果你是 Additional Variation Images 的订阅者，今天什么都不用做；需要你操作时，我们会通过邮件联系你。