标题：解决 WooCommerce 自定义邮件重复发送问题的完整指南_技术教程

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 操作。遵循这一原则，即可彻底杜绝双发问题，并提升代码可维护性与健壮性。