WordPress 'template_include' 过滤器失效：自定义文章类型模板无法加载

这种复制粘贴改名称却踩坑的情况我碰到过好多次，大概率是细节没改到位，咱们一步步排查解决：

1. 先核对模板文件命名规则 #

WordPress对自定义文章类型的模板命名有严格要求：如果你的自定义文章类型slug是new_custom_post，那单篇文章模板必须是single-new_custom_post.php——下划线、大小写必须完全匹配！很多时候复制旧代码后，只改了函数和类型名，却忘了同步修改模板文件名；或者本地Windows开发不区分大小写，但服务器是Linux，大小写错了直接找不到文件。

2. 检查过滤器里的类型判断逻辑 #

你说只修改了函数名和文章类型名称，那重点看is_singular()里的参数是不是对应新的文章类型slug：
比如旧代码可能是：

function old_type_template($template) {
    if (is_singular('old_post_type')) {
        // 加载模板逻辑
    }
    return $template;
}
add_filter('template_include', 'old_type_template');

新代码里一定要把is_singular('old_post_type')改成你的新文章类型slug（注意是注册时的rewrite['slug']值，不是注册函数里的类型名，如果没指定slug才默认用类型名）。

可以加个调试日志确认当前匹配的类型：

function new_type_template($template) {
    // 临时写日志，看当前访问的文章类型
    error_log('Current post type: ' . get_post_type());
    if (is_singular('new_post_type_slug')) {
        $target_template = locate_template(array('single-new_post_type_slug.php'));
        if (!empty($target_template)) {
            return $target_template;
        }
    }
    return $template;
}
add_filter('template_include', 'new_type_template');

然后去服务器的错误日志里看输出，确认当前访问的文章类型是不是你要的那个。

3. 确认模板文件的路径查找逻辑 #

如果你的模板是放在插件目录里（不是主题目录），locate_template()默认只会搜索主题/子主题文件夹，这时候得手动指定插件内的模板路径：

function new_type_template($template) {
    if (is_singular('new_post_type')) {
        // 替换成你插件里的模板实际路径
        $plugin_template = plugin_dir_path(__FILE__) . 'templates/single-new_post_type.php';
        if (file_exists($plugin_template)) {
            return $plugin_template;
        }
    }
    return $template;
}
add_filter('template_include', 'new_type_template');

注意plugin_dir_path(__FILE__)的路径是否正确——如果这个函数写在插件的子文件夹里，可能需要用dirname(__FILE__)多嵌套一层来定位到插件根目录。

4. 刷新固定链接规则 #

自定义文章类型注册后，WordPress的固定链接规则可能没同步更新，导致系统识别不到这个类型的单页，直接 fallback 到默认模板或者404。去后台「设置」→「固定链接」，随便切换一个选项保存，再切回原来的设置保存，强制刷新规则。

5. 检查过滤器优先级冲突 #

如果多个插件都用了template_include过滤器，优先级低的函数可能被覆盖。给你的新过滤器加个更高的优先级试试：

// 数字越大优先级越高，99是比较高的数值
add_filter('template_include', 'new_type_template', 99);

终极调试技巧 #

如果还是找不到问题，直接强制返回模板路径测试：

function new_type_template($template) {
    // 强制返回插件内的模板，看是否能加载
    return plugin_dir_path(__FILE__) . 'templates/single-new_post_type.php';
}
add_filter('template_include', 'new_type_template');

如果这样能正常加载模板，说明是前面的类型判断或路径查找逻辑有问题；如果还是不行，那要么是模板文件本身有语法错误，要么是路径完全写错了。

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