WooCommerce 10.4 已于 2025 年 12 月 10 日正式发布。本次版本更新并不是简单的功能补充，而是一次围绕性能、前端架构、API 体系与长期可维护性的系统性升级。对于正在运营中大型电商网站、采用 Headless 架构，或高度依赖 REST API 的站点来说，WooCommerce 10.4 具备非常明确的升级价值。
一、WooCommerce 10.4 版本信息总览
WooCommerce 10.4.0 是一个完全向后兼容的稳定版本，但需要注意的是，本次更新包含数据库更新，在升级前仍建议进行完整备份。
核心信息如下：
- 发布时间：2025 年 12 月 10 日
- 当前版本：WooCommerce 10.4.0
- 向后兼容：是
- 数据库更新：包含
- 提交次数：340
- 贡献者人数：69
从整体方向来看，本次更新主要聚焦在以下几个方面：
- 前端交互架构的现代化
- REST API 性能优化
- 高性能订单存储体系的成熟
- 区块系统可扩展能力增强
- 无障碍访问标准的持续改进
二、Interactivity API Mini Cart 成为默认方案（#60823）
WooCommerce 10.4 中最具代表性的变化之一，是 Interactivity API Mini Cart 正式成为默认启用的迷你购物车方案。这意味着 WooCommerce 正在全面拥抱 WordPress 原生的现代前端交互体系。
2.1 Mini Cart 架构变化带来的意义
新的 Mini Cart 不再依赖旧有的 React 实现，而是基于 WordPress Interactivity API 构建，这一调整带来了多方面的好处：
- JavaScript 资源体积更小
- 页面交互响应更快
- 与 WordPress 原生前端模式高度一致
- 更有利于长期维护与生态统一
这一功能此前需要通过实验性开关启用，而在 10.4 中已经被认为足够稳定，可直接用于生产环境。
2.2 开发者与站点维护者需要注意什么
对于有定制需求的站点，需要重点关注以下几点：
- 自定义 Mini Cart 行为的插件和主题需要进行兼容性测试
- 旧版 React Mini Cart 目前仍可使用，但已明确进入未来淘汰路径
- 新功能应优先采用 Interactivity API 推荐的扩展方式
三、REST API 加载机制优化，性能明显提升（#60684）
3.1 Admin 与 Analytics API 改为按需加载
在此前的版本中，WooCommerce 的 wc-admin 与 wc-analytics REST API 控制器会在每一次 REST API 请求中被加载，即便请求并不涉及后台或数据分析功能。
WooCommerce 10.4 对这一机制进行了重要调整：
- Admin 与 Analytics API 仅在被实际调用时加载
- 非相关请求不再承担额外初始化成本
3.2 性能改进带来的实际影响
根据官方测试数据，这一改动带来的收益非常直接：
- 不使用分析接口的 API 请求，TTFB 可缩短约 30–60ms
- 消除了此前每次请求额外约 100ms 的无效消耗
这一优化对以下场景尤为关键：
- 高访问量 WooCommerce 商店
- Headless WooCommerce 架构
- 移动端应用调用 REST API
- 第三方系统、ERP、CRM 接口对接
四、HPOS Datastore 缓存正式成为标准功能（#61521）
High-Performance Order Storage 是 WooCommerce 近年来重点推进的订单数据架构。在 10.4 版本中，HPOS Datastore 缓存功能正式从实验状态毕业，成为可稳定使用的标准功能选项。
4.1 HPOS 缓存能解决什么问题
在订单量较大的站点中，频繁的订单查询往往是数据库性能瓶颈的主要来源。启用 HPOS 缓存后，可以：
- 缓存高频订单查询结果
- 显著降低数据库负载
- 提升后台操作与 API 请求的整体响应速度
4.2 当前启用策略与未来规划
需要注意的是：
- WooCommerce 10.4 中该功能并未默认开启
- 官方建议开发者与服务商在合适的环境中主动启用并评估效果
- 未来版本可能在确认更广泛稳定性后默认开启
五、区块系统能力持续增强（#60779）
5.1 Featured Product 与 Featured Category 支持 Inner Blocks
WooCommerce 10.4 对精选产品与精选分类区块进行了结构性升级，正式支持 Inner Blocks。
这一变化意味着：
- 不再依赖固定开关控制标题、价格和描述显示
- 可以自由调整各元素顺序
- 支持插入额外区块，例如按钮、文本或图标
- 各元素可独立进行样式控制
同时，系统新增了 Category Title 和 Category Description 内部区块，用于配合新的结构模式。
5.2 Cart 与 Checkout 区块视觉优化
购物车与结账区块在本次版本中也获得了细节层面的优化，包括：
- 字体尺寸更加统一
- 表单间距更加合理
- 支付方式与订单摘要区域更清晰
整体视觉更简洁，有助于提升结账流程的可读性与转化体验。
六、无障碍访问体验持续改进
WooCommerce 10.4 继续推进对 WCAG 2.2 标准的支持，在多个细节层面进行了优化。
6.1 产品集合轮播的可访问性提升
针对 Product Collections Carousel，官方进行了多项改进：
- 可聚焦图片区域更大
- 上一页与下一页按钮标签更清晰
- 在移动端和页面缩放状态下按钮始终可见
6.2 邮件模板语义结构优化
WooCommerce 所有邮件模板中的表格结构进行了统一优化：
- 数据表格使用正确的
<th scope="row"> - 布局表格统一添加
role="presentation" - 辅助技术可以正确区分布局与数据内容
七、API 新增、修复与性能优化汇总
7.1 新增 API 能力
WooCommerce 10.4 新增了多项接口能力，包括：
- 通过实例 ID 获取单个配送区域方法的 GET 接口
- v3 API 中新增
/products/catalog接口（需功能标记） - Agentic Commerce 结账会话与完成接口（实验）
- Agentic Commerce Webhook 支持
- 购物车商品项数据字段支持 HTML 标签
7.2 修复与性能改进
- 修复产品与变体接口分页返回重复数据的问题
- 减少 Orders Controller 中不必要的
get_product调用，提升性能
八、Store API 限流逻辑修正（#62076）
此前，WooCommerce Store API 的限流逻辑会错误地将 PUT 请求计入限流次数，导致用户在结账过程中可能意外触发限制。
在 10.4 中，这一问题已被修复：
- 限流仅作用于 POST 请求
- 切换支付方式或更新结账数据不再受影响
这一调整显著改善了实际结账体验。
九、REST API 体系的进一步完善（#60684）
9.1 Analytics API 按需加载再次强化性能优势
随着 Analytics API 改为按需加载，WooCommerce 的 REST API 架构更加适合 Headless 和高性能应用场景，减少了不必要的资源消耗。
9.2 Customers v4 接口正式上线（#61336，#61507）
全新的 Customers v4 接口引入了更现代化的设计，并支持更多排序维度，例如：
- 姓名
- 邮箱
- 注册时间
- 订单数量
- 总消费金额
这为客户管理系统、CRM 集成和数据分析提供了更大的灵活性。
总结
WooCommerce 10.4 并不是一次追求噱头的版本更新，而是一轮围绕性能、现代架构与长期稳定性展开的扎实升级。无论是前端交互、API 性能，还是订单数据存储体系，都朝着更高效、更可扩展的方向迈进了一步。
把症状、错误提示和最近改动发过来。
我们先判断风险、可能原因和安全下一步，再决定是否需要登录后台或服务器。