WordPress主题开发singular.php/index.php不显示内容问题

核心排查方向按优先级排序 #

• 第一步：验证主题合法性
  WordPress识别可用主题的核心前提是主题根目录存在style.css文件，且文件头部必须包含合法的主题声明注释。如果style.css被放到了css子目录、头部注释格式错误、文件权限不足，会直接导致主题加载逻辑异常：这类异常下经常出现page.php偶然可访问、但singular.php/index.php直接返回空白源码的情况。
  确认style.css在主题根目录，且文件开头包含如下格式的声明：

  /*
  Theme Name: 自定义主题名
  Author: 主题作者
  Version: 1.0
  */
  

• 第二步：检查文件基础属性
  对比能正常运行的page.php文件，确认两个失效文件的属性一致：
  1. 文件权限统一为644，所在主题目录权限为755，避免服务器进程无读取权限
  2. 文件编码统一为UTF-8 无BOM格式，带BOM的文件会触发PHP输出头异常，直接返回空白页
  3. 文件名严格小写，Windows环境下大小写不敏感但Linux服务器大小写敏感，不要写成Singular.php、Index.php
• 第三步：修正模板代码结构错误
  当前模板代码存在结构冲突：get_header()函数会自动加载header.php，而标准header.php本身已经包含<!DOCTYPE html>、<head>、<body>起始标签，在模板里重复写整套HTML文档头部会导致DOM结构错乱，部分环境下会被安全规则拦截输出。
  修正后的标准singular.php代码参考：

  <?php
  get_header();
  get_template_part('template-parts/header/header-bar');
  
  if (have_posts()):
    while (have_posts()) : the_post();
      the_content();
    endwhile;
  else:
    echo '<p>暂无匹配内容</p>';
  endif;
  
  get_footer();
  

• 第四步：排除路由与钩子干扰
  1. 到后台「设置-固定链接」页面直接点击「保存更改」，不需要修改配置，目的是刷新固定链接重写规则，避免路由匹配错乱
  2. 关闭所有缓存插件、清空服务器缓存与浏览器缓存后测试，排除缓存强制加载旧模板的问题
  3. 检查functions.php中是否存在template_include相关的自定义过滤器逻辑，这类钩子如果返回错误的模板路径，会直接导致对应模板加载空白，可以临时注释相关代码测试

快速验证技巧：在singular.php最顶部第一行加入代码wp_die('singular模板已加载');，访问单篇文章/单页，如果能看到提示文字说明文件已经被WordPress正常识别，问题出在后续模板代码；如果仍然空白，回到前两步检查主题合法性与文件属性。

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