如何通过自定义插件覆盖WooCommerce的customer-completed-order邮件模板

首先给出修正后的可用代码：

// 放在插件根目录的主入口php文件中
add_filter( 'woocommerce_locate_template', 'custom_override_wc_email_template', 99, 3 );
function custom_override_wc_email_template( $template, $template_name, $template_path ) {
    // 精准匹配目标模板，避免模糊匹配误判
    if ( 'customer-completed-order.php' === $template_name ) {
        // 示例插件内模板存放路径：插件根目录/templates/woocommerce/emails/customer-completed-order.php
        $custom_template = trailingslashit( plugin_dir_path( __FILE__ ) ) . 'templates/woocommerce/emails/' . $template_name;
        // 确认自定义模板文件存在再返回，避免页面报错
        if ( file_exists( $custom_template ) ) {
            return $custom_template;
        }
    }
    return $template;
}

原代码失效的常见原因及修复逻辑 #

• 匹配逻辑错误：原代码使用strpos做弱类型判断，如果匹配到的字符串位置在开头（返回值为0），会被判定为false导致条件不触发，直接用全等匹配精准判断模板名更稳妥。
• 路径拼接错误：如果挂载钩子的代码不是放在插件根目录的主文件中，plugin_dir_path( __FILE__ )会拿到当前文件所在的子目录路径，导致模板路径拼接错误。建议把这段代码放在插件根目录的入口文件中，确保路径指向正确。
• 优先级被覆盖：设置更高的优先级（比如99），避免主题或其他插件的同钩子逻辑覆盖你的修改。
• 文件不存在或权限异常：要确保插件内的模板文件路径和代码中拼接的路径完全一致，同时文件权限正常，PHP进程可以正常读取该文件。

生效验证步骤 #

• 测试时在WooCommerce后台订单详情页，选择重新发送订单完成邮件，不要用历史收到的邮件判断是否生效。
• 若仍未生效，可在钩子函数内临时加调试代码，打印$template_name和$custom_template的值，确认是否命中判断、路径是否正确。

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