WordPress Twenty Seventeen静态首页无法执行自定义模板

嘿，这个问题我之前帮不少开发者踩过坑，本质是WordPress处理静态首页和普通页面的逻辑有差异，再加上Twenty Seventeen主题自带的首页模板优先级规则，咱们一步步来排查解决：

1. 先确认自定义模板的基础设置是否正确 #

• 检查模板文件头部的注释，必须包含Template Name让WordPress识别，比如：

  <?php
  /*
  Template Name: Book List
  */
  get_header();
  // 你的自定义代码
  get_footer();
  ?>
  

• 确保模板文件名没有和主题自带的模板冲突，比如别命名为front-page.php（父主题已经有这个文件，优先级更高）。

2. 验证后台首页设置是否准确 #

登录WordPress后台，进入设置 > 阅读，确认：

• 选中「静态页面」选项
• 「首页」下拉框里确实选了你的自定义模板页面（Book List）
• 别不小心把「博客页面」也选成同一个页面了，这会导致逻辑混乱。

3. 修正模板中的条件判断逻辑 #

很多自定义模板里会用is_page()来判断当前页面，但当这个页面被设为静态首页后，is_front_page()才是判断首页的正确函数，is_page()可能失效。你需要把模板里的条件判断改成同时兼容两种情况：

// 替换原来的is_page()判断
if ( is_front_page() || is_page( 'book-list' ) ) {
    // 这里放你的自定义代码，比如书籍列表渲染逻辑
}

4. 处理Twenty Seventeen的首页模板优先级 #

Twenty Seventeen父主题自带front-page.php，WordPress会优先加载这个文件，而不是你的自定义页面模板。解决办法有两个：

方法一：直接覆盖front-page.php #

在子主题目录下新建front-page.php文件，把你自定义模板里的所有代码复制进去，这样首页就会直接使用这个子主题的文件。

方法二：用过滤器强制加载自定义模板 #

如果不想修改front-page.php，可以在子主题的functions.php中添加以下代码，强制WordPress在首页加载你的自定义模板：

function force_custom_front_page_template( $template ) {
    // 检查是否是静态首页
    if ( is_front_page() ) {
        // 替换成你的自定义模板文件名
        $custom_template = locate_template( array( 'template-book-list.php' ) );
        if ( ! empty( $custom_template ) ) {
            return $custom_template;
        }
    }
    return $template;
}
add_filter( 'template_include', 'force_custom_front_page_template', 99 );

5. 最后别忘了清除缓存 #

不管是服务器缓存、CDN缓存还是WordPress插件缓存，都先清一遍，有时候缓存会导致修改后的代码无法即时生效。

按照上面的步骤排查，应该就能解决静态首页只显示正文、模板代码不执行的问题了。

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