EP208. “WP 6.4 改变：Block Theme 单篇内容不再需要 while 循环”

一个延续了 20 年的 WordPress 惯例被打破：从 WordPress 6.4 开始，Block Theme 处理「单篇」内容（单篇文章、单个页面、单个自定义文章类型详情页等）时，WordPress 会自动帮你跑好主查询的循环，不再需要开发者自己手写 while (have_posts()) { the_post(); ... }。如果继续沿用旧写法，单篇内容的模板会直接空白/报错——因为 have_posts() 这时候已经被 WordPress 提前跑过一次、循环指针耗尽了，你自己再跑一次自然拿不到数据。这一讲不是这门课「新建」的内容，而是给已经写好的、沿用 20 年传统写法的模板文件打一个必要的补丁。

涉及文件

• 本讲影响所有「单篇」类型的自定义 Block PHP 文件（下一讲 EP209 才会新建 singlepost.php/page.php，这一讲用作者已有的成品参考版本演示问题和修法）

核心概念

• 过去 20 年的传统写法：不管是不是「只显示一篇内容」的场景，WordPress 主题开发者都被教导要写 while (have_posts()) { the_post(); ... } 包住输出逻辑——哪怕单篇详情页逻辑上根本不需要循环（反正只有一篇）。官方给出的历史原因包括：习惯沿袭、担心某些插件依赖「处于循环上下文」这个假设、没有明确的反对理由
• WordPress 6.4 引入的改变：官方博客明确说明，从这个版本起，Block Theme 在渲染「单篇」内容时，会自动把模板输出包在主查询循环里——也就是说 WordPress 自己已经替你调用过 have_posts()/the_post()
• 为什么旧代码会直接报错/空白：如果模板文件里依然手写 while (have_posts()) { the_post(); ... }，这时候 have_posts() 会返回 false（因为 WordPress 已经预先把这个循环指针推进消耗完了），整个 while 循环体一次都不会执行，页面自然什么都不输出；如果强行调用 the_post()，还可能直接报错
• 修法极其简单：把「单篇」模板里的 while (have_posts()) { the_post(); 这一整行开头，以及循环体末尾对应的收尾 }，直接删掉——只保留中间原本的输出逻辑，不需要循环包裹，因为 WordPress 已经处理好了
• 这个修法只适用于「单篇」场景：像博文列表/归档页这种「一次展示多篇内容」的场景，while 循环依然是必需的（因为确实需要遍历多篇文章），不能把这条规则错误地推广到所有模板文件
• 为什么这门课选择「打补丁」而不是「重录整章」：这个改变发生在 WordPress 20 年历史的中段，作者明确说明不打算把整个 Block Theme 章节按新规则重新录制，而是通过这类「勘误提醒」的方式，让学习者理解「过去为什么这样写」和「现在为什么要改」——因为现实中大概率会长期接触到大量沿用旧写法的既有主题/教程,理解这段历史变迁本身也是有价值的知识

常见坑

• 升级到 WordPress 6.4 及以上版本后，Block Theme 里「单篇」类型的模板文件依然保留旧的 while (have_posts()) { the_post(); ... } 写法——页面会直接空白或报错，因为 WordPress 已经预先跑过这个循环
• 把这条「单篇内容不需要 while 循环」的规则错误地应用到列表/归档类页面——这类页面依然需要手写循环遍历多篇内容，删掉循环反而会导致只显示不完整的内容或报错
• 排查这类问题时，误以为是自己代码某处逻辑错误，没有意识到这是 WordPress 版本升级带来的行为变化

[截图：WordPress 6.4+ 环境下单篇模板仍保留旧版 while 循环写法时，前台页面正文完全空白的效果]

延伸 / 后续讲座会用到

下一讲开始正式创建单篇文章、页面等模板对应的自定义 Block（singlepost/page/blogindex），会应用这一讲学到的规则——单篇类模板不写 while 循环，列表类模板（比如博文列表）依然保留。

Sources

Udemy：

• Become a WordPress Developer: Unlocking Power With Code — Section 28, EP208