WooCommerce自定义邮件类无法找到插件内模板的问题排查

一、检查woocommerce_locate_template钩子的挂载时机与优先级 #

• 钩子必须在WooCommerce加载完成后挂载，否则会因钩子未注册导致无法触发。建议将钩子挂载到plugins_loaded动作后，避免时机过早：

add_action('plugins_loaded', function() {
    add_filter('woocommerce_locate_template', 'lockoloop_locate_custom_email_template', 10, 3);
});

function lockoloop_locate_custom_email_template($template, $template_name, $template_path) {
    // 仅拦截我们的自定义邮件模板
    if ('customer-ready-order.php' === $template_name) {
        $custom_template = LOCKOLOOP_CUSTOMIZER_PATH . 'templates/backend/emails/' . $template_name;
        if (file_exists($custom_template)) {
            error_log('已匹配自定义邮件模板：' . $custom_template); // 用于测试触发状态
            return $custom_template;
        }
    }
    return $template;
}

• 确保插件主文件中正确定义根路径常量：

define('LOCKOLOOP_CUSTOMIZER_PATH', plugin_dir_path(__FILE__));

二、调整邮件类的模板路径指定逻辑 #

WooCommerce邮件类默认会优先去主题或核心模板目录查找，直接设置template_html无法指向插件内路径，需手动指定template_base属性：

class WC_Email_Ready_Pickup extends WC_Email {
    public function __construct() {
        $this->id             = 'ready_pickup';
        $this->title          = '待自提通知';
        $this->description    = '订单状态变为待自提时发送给客户的通知邮件';
        $this->template_html  = 'customer-ready-order.php';
        $this->template_plain = 'plain/customer-ready-order.php';
        // 关键：指定插件内模板的基础路径
        $this->template_base  = LOCKOLOOP_CUSTOMIZER_PATH . 'templates/backend/emails/';

        parent::__construct();

        $this->recipient = $this->get_option('recipient', get_option('admin_email'));
    }
}

设置template_base后，邮件类会直接从插件目录加载模板，无需依赖过滤器（过滤器可作为降级方案保留）。

三、排查钩子未触发的核心原因 #

1. 文件加载问题：确认ready-pickup-status.php已被插件主文件正确引入（用require_once或include），避免钩子所在文件未加载。
2. 拼写错误：检查过滤器函数名、模板文件名是否完全匹配，大小写敏感。
3. 日志验证：开启wp-config.php中的WP_DEBUG和WP_DEBUG_LOG，查看是否有函数未定义、路径不存在等错误日志。
4. 触发动作验证：手动将订单状态改为“待自提”，确认邮件类已被实例化并执行了模板查找流程。

四、验证路径常量的准确性 #

即使常量在其他场景正常，仍需在过滤器或邮件类中添加日志验证路径：

error_log('插件根路径：' . LOCKOLOOP_CUSTOMIZER_PATH);

确保路径结尾包含斜杠，或拼接时手动添加，避免出现lockoloop-customizertemplates/backend/emails这类无效路径。

内容的提问来源于stack exchange，提问作者Zealot