如何让自定义插件的WooCommerce模板覆盖优先级高于主题

• 站点在W3C Validator平台检测时出现WooCommerce相关错误
• 最初尝试通过重定向WooCommerce目标文件的模板路径覆盖对应模板，修复报错

当前使用的WordPress主题同样覆盖了自定义插件需要修改的同名模板文件，主题的模板覆盖逻辑抵消了插件的覆盖功能，导致插件修改不生效。 #

当前使用WordPress内置add_filter()函数挂载自定义模板定位函数，设置优先级为1，目标覆盖的模板文件路径为woocommerce/templates/single-product/add-to-cart/variable.php，代码如下：

function wc_locate_template( $template, $template_name, $template_path ) {
    // 检测站点是否存在可用WooCommerce
    if ( empty( $template ) || ! is_callable( 'WC' ) || ( defined( 'WC_TEMPLATE_DEBUG_MODE' ) && WC_TEMPLATE_DEBUG_MODE ) ) {
        return $template;
    }

    // 路径定义
    $default_path = WC()->plugin_path() . '/templates/';
    $plugin_path  = untrailingslashit( plugin_dir_path( __FILE__ ) ) . '/templates/';
    $template_new = str_replace( $default_path, $plugin_path, $template );

    // 模板替换逻辑
    if (
        false !== strpos( $template, $default_path )
        && file_exists( $template_new )
    ) {
        $template = $template_new;
    }

    return $template;
}
add_filter( 'woocommerce_locate_template', 'wc_locate_template', 1, 3 );

如何设置自定义插件的模板覆盖逻辑与优先级，确保插件的WooCommerce模板覆盖不会被主题的同名模板覆盖逻辑抵消，实现插件级别的模板优先加载？

原有代码失效的核心原因有两点：

1. 过滤器优先级设置不够高，主题挂载的同钩子函数先执行，已经把模板路径替换成主题内的模板路径，原有判断逻辑只匹配WooCommerce默认插件路径，无法识别主题传入的模板路径
2. 替换逻辑依赖传入的模板路径字符串匹配，没有直接用钩子传入的$template_name参数做判断，兼容性差

调整步骤：

• 将woocommerce_locate_template过滤器的优先级设为0，高于WordPress常规钩子默认优先级10，也高于主题常用的优先级1-10，确保自定义逻辑最先执行
• 直接通过$template_name（即模板相对于WooCommerce templates目录的相对路径）判断是否为需要覆盖的目标模板，不依赖传入的$template路径，跳过主题模板替换逻辑
• 配置强制覆盖模板白名单，避免无差别替换所有WooCommerce模板影响站点其他功能

修改后可直接使用的代码：

function custom_plugin_force_wc_template( $template, $template_name, $template_path ) {
    // 基础环境校验，WooCommerce不存在或开启模板调试模式时直接返回原路径
    if ( empty( $template ) || ! is_callable( 'WC' ) || ( defined( 'WC_TEMPLATE_DEBUG_MODE' ) && WC_TEMPLATE_DEBUG_MODE ) ) {
        return $template;
    }

    // 配置需要插件强制优先加载的模板列表，新增覆盖模板直接往数组里加相对路径即可
    $override_list = [
        'single-product/add-to-cart/variable.php'
    ];

    if ( in_array( $template_name, $override_list, true ) ) {
        $plugin_template_path = untrailingslashit( plugin_dir_path( __FILE__ ) ) . '/templates/' . $template_name;
        if ( file_exists( $plugin_template_path ) ) {
            // 直接返回插件内模板路径，跳过后续主题模板判断逻辑
            return $plugin_template_path;
        }
    }

    return $template;
}
add_filter( 'woocommerce_locate_template', 'custom_plugin_force_wc_template', 0, 3 );

注意事项：

• 插件内的模板目录结构必须和WooCommerce原生templates目录结构完全一致，例如上述variable.php在插件内的存放路径必须是你的插件根目录/templates/single-product/add-to-cart/variable.php
• 如需新增其他强制覆盖的WooCommerce模板，直接将模板相对路径添加到$override_list数组中即可
• 该逻辑优先级最高，会优先于主题、WooCommerce默认模板加载，仅用于必须插件级生效的模板修改场景

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