woocommerce 插件开发中，自定义邮件类被意外实例化两次，导致客户收到重复邮件。本文详解根本原因（类文件内 `return new` 与主函数中 `new` 双重实例化），并提供安全、可维护的修复方案。
在 WooCommerce 插件开发中，为订单完成时自动发送含授权码的定制邮件（如 Foundry_Code_Email）是常见需求。然而，许多开发者会遇到一个隐蔽却高频的问题：同一封邮件被发送两次。尽管邮件逻辑、模板和钩子（如 woocommerce_order_status_completed_notification）看似无误，问题往往潜藏在类加载与实例化的机制中。
? 根本原因：双重实例化
问题核心并非钩子触发逻辑或 trigger() 方法本身，而是 Foundry_Code_Email 类被初始化了两次：
- ✅ 第一次：在 class-foundry-code-email.php 文件末尾显式执行 return new Foundry_Code_Email();
- ✅ 第二次：在主插件函数（如 fpc_custom_woocommerce_emails）中再次调用 new Foundry_Code_Email() 并注册到 $email_classes
这意味着：当 WooCommerce 加载邮件类时，该类对象被构造两次，而每次构造都会绑定一次 woocommerce_order_status_completed_notification 钩子——最终导致 trigger() 被执行两次，邮件发送两遍。
? 正确做法：单点实例化 + 延迟加载
WooCommerce 的 woocommerce_email_classes 过滤器期望你返回已实例化的对象引用，而非类名或未实例化的类。因此，必须确保整个生命周期中仅存在一个实例。以下是推荐实践：
✅ 修复后的主函数（推荐）
function fpc_custom_woocommerce_emails( $email_classes ) {
$plugin_dir = dirname(__DIR__);
// ✅ 使用 include_once 并直接接收返回的对象（即 new Foundry_Code_Email() 的结果）
// 注意：class-foundry-code-email.php 文件末尾必须保留 return new Foundry_Code_Email();
$email_classes['foundry_code_email'] = include_once $plugin_dir . '/Includes/class-foundry-code-email.php';
return $email_classes;
}
add_filter( 'woocommerce_email_classes', 'fpc_custom_woocommerce_emails' );✅ 同时确保类文件末尾仅返回单例（保持原样）
// class-foundry-code-email.php 末尾（关键！）
if ( ! defined( 'ABSPATH' ) ) exit;
if ( ! class_exists( 'Foundry_Code_Email', false ) ) {
// ... 类定义 ...
}
return new Foundry_Code_Email(); // ✅ 必须保留，且仅此一处 new⚠️ 注意命名一致性：$email_classes 键名应使用小写蛇形（如 'foundry_code_email'），与类中 $this->id = 'foundry_code_email' 严格匹配，否则 WooCommerce 无法识别并启用该邮件。
? 额外加固建议（防患未然）
-
钩子去重保护（可选但推荐）
在 trigger() 方法开头添加幂等性检查，避免因其他异常路径导致重复：public function trigger( $order_id, $order = false ) { if ( ! $order_id || get_post_meta( $order_id, 'foundry_code_email_sent', true ) ) { return; // 已发送，直接退出 } // ... 原有逻辑 } -
禁用 WordPress 默认邮件钩子干扰
若你仅希望在特定业务流程（如自定义支付回调）中发送，不要依赖 woocommerce_order_status_completed_notification —— 它可能被多种场景触发（如后台手动改状态）。改用更精确的钩子，例如：add_action( 'woocommerce_thankyou', array( $this, 'trigger_on_thankyou' ), 10, 1 ); // 或配合订单状态检查
-
日志验证
临时加入调试日志确认是否真为双重触发：error_log("Foundry email triggered for order #{$order_id} at " . current_time('mysql'));
✅ 总结
重复邮件的本质是 PHP 文件加载机制与 WooCommerce 邮件注册逻辑的耦合失误。切记：WooCommerce 邮件类文件应「只负责定义类 + 返回单例」；主注册函数应「只负责包含文件 + 接收并注册该实例」。二者不可同时执行 new 操作。遵循这一原则，即可彻底杜绝双发问题，并提升代码可维护性与健壮性。
