在 WooCommerce 中为自定义订单状态（如 wc-order-confirmed）添加事务性邮件时，即使正确注册了邮件类和状态，邮件仍不触发——根本原因在于未将对应的状态变更动作（action）显式加入 woocommerce_email_actions 过滤器。
在 woocommerce 中为自定义订单状态（如 `wc-order-confirmed`）添加事务性邮件时，即使正确注册了邮件类和状态，邮件仍不触发——根本原因在于未将对应的状态变更动作（action）显式加入 `woocommerce_email_actions` 过滤器。
WooCommerce 的事务性邮件系统采用“事件驱动”机制：邮件发送并非由状态本身直接触发，而是依赖于特定的 hook action（例如 woocommerce_order_status_processing_to_completed）。当订单状态发生变更时，WooCommerce 内部会动态触发形如 woocommerce_order_status_{from}_to_{to} 或简化的 woocommerce_order_status_{to} 的动作钩子；而只有当这些钩子名称被明确列入 woocommerce_email_actions 过滤器返回的数组中时，对应的 WC_Email 实例才会被激活并执行 trigger() 方法。
你已正确完成了以下关键步骤：
- 通过 wc_order_statuses 和 woocommerce_register_shop_order_post_statuses 注册自定义状态（如 wc-order-confirmed）；
- 通过 woocommerce_email_classes 引入自定义邮件类（如 WC_Customer_Order_Confirmed）；
- 邮件类中也遵循了官方规范（继承 WC_Email、定义 id、title、template_path 等，并在 trigger() 中调用 setup_locale() + get_content_html() 等）。
但遗漏了最关键的一步：告知 WooCommerce 哪些状态变更动作应触发邮件发送。默认情况下，WooCommerce 仅预置了标准状态（如 processing、completed、on-hold）相关的 action 名称，所有以 wc- 开头的自定义状态均需手动声明。
✅ 正确做法是：在插件初始化阶段，使用 woocommerce_email_actions 过滤器显式追加你的自定义状态所对应的 action 名称。注意命名规则：
- 若监听「任意状态 → 目标状态」的通用变更（推荐），使用 woocommerce_order_status_{slug}（如 woocommerce_order_status_order-confirmed）；
- 若需精确控制「某源状态 → 某目标状态」（如仅 on-hold → cancelled），则用 woocommerce_order_status_{from}_to_{to}（如 woocommerce_order_status_on-hold_to_cancelled）。
以下是必须添加的核心代码段（建议置于主类构造函数中，与其它 add_filter 同级）：
// 在 WC_LR_custom_order_statuses::__construct() 中添加
add_filter('woocommerce_email_actions', [$this, 'filter_woocommerce_email_actions'], 10, 1);
/**
* 将自定义订单状态变更动作注册到邮件触发白名单
*/
public function filter_woocommerce_email_actions($actions) {
// 通用触发：只要订单变为该状态即发信（最常用）
$actions[] = 'woocommerce_order_status_order-confirmed';
$actions[] = 'woocommerce_order_status_payment-await';
$actions[] = 'woocommerce_order_status_payment-received';
$actions[] = 'woocommerce_order_status_order-shipped';
$actions[] = 'woocommerce_order_status_order-done';
// 精确触发：仅当从 on-hold 变更为 cancelled 时发信
$actions[] = 'woocommerce_order_status_on-hold_to_cancelled';
return $actions;
}⚠️ 重要注意事项：
- Action 名称中不带 wc- 前缀：WooCommerce 内部自动剥离 wc-，因此 wc-order-confirmed 对应的 action 是 order-confirmed，而非 wc-order-confirmed；
- 确保邮件类 id 与 action 命名逻辑一致：例如 WC_Customer_Order_Confirmed 类的 $this->id 应为 customer_order_confirmed，其内部 trigger() 方法需能接收订单参数并正确设置模板变量；
- 调试技巧：若仍不生效，可在 trigger() 方法开头添加 error_log("Email triggered for order #{$order_id}");，并配合 wp_debug_log 查看是否进入方法；同时检查 WordPress 后台「WooCommerce → 状态 → 日志」中是否有邮件发送错误；
- 避免重复注册：确保该过滤器只添加一次，且在 woocommerce_email_classes 之后执行（优先级 10 足够）。
总结：WooCommerce 邮件系统的“可扩展性”建立在显式声明机制之上。woocommerce_email_actions 是连接自定义状态与邮件逻辑的桥梁——它不是可选配置，而是必填清单。补上这一环后，你的 WC_Customer_Order_Confirmed 等邮件将立即按预期在订单状态更新时稳定触发。
