自定义模板未显示在模板下拉列表及相关问题求助

一、关于WordPress模板扫描机制 #

当前WordPress已优化模板扫描逻辑，不再固定每小时扫描一次，但缓存、路径权限或代码格式问题仍可能导致模板列表不更新。

二、针对问题的具体修复步骤 #

1. 清理旧模板名称残留 #

旧模板名称仍显示是因为WordPress在数据库wp_options表中缓存了模板列表，可通过以下方式清理：

• 进入后台「设置」→「固定链接」，直接点击「保存更改」，此操作会触发全局缓存刷新，包括模板列表。
• 若无效，可手动清理数据库缓存（先备份数据库），执行SQL语句：

  DELETE FROM wp_options WHERE option_name LIKE '_wp_theme_%_templates';
  

  注：wp_需替换为你的数据库表前缀。

2. 找回消失的模板 #

• 检查templates文件夹权限：设置为755，模板文件权限设为644，确保WordPress能读取文件。
• 核对模板文件注释格式：Template Name必须在PHP代码最顶部的注释块，格式严格如下：

  <?php
  /*
  Template Name: 我的新模板1
  */
  // 后续业务代码
  ?>
  

  注意注释块需正确闭合，Template Name:后要有空格，名称避免特殊字符。
• 排查主题functions.php：确认没有通过theme_page_templates钩子限制模板加载的自定义代码，这类代码可能阻止新路径下的模板被识别。

3. 强制刷新模板列表的通用方法 #

• 若服务器支持WP-CLI，执行命令：

  wp cache flush
  wp theme scan
  

  直接刷新缓存并重新扫描主题模板。
• 无WP-CLI时，可临时在主题functions.php中添加以下代码，访问任意页面后删除：

  function force_refresh_templates() {
      delete_transient( 'wp_theme_' . get_stylesheet() . '_page_templates' );
      delete_transient( 'wp_theme_' . get_template() . '_page_templates' );
  }
  add_action( 'init', 'force_refresh_templates' );
  

三、后续注意事项 #

• 模板需放在主题根目录下的templates文件夹，WordPress默认识别该路径下的自定义模板，无需额外配置。
• 重命名模板后，建议手动重新关联页面，避免依赖旧缓存的关联关系。

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