跳到正文
参考

WordPress 区块主题模板层级

完整的区块主题（全站编辑）模板层级：针对每种请求类型，列出 WordPress 依次查找的模板顺序，从最具体的开始，最终回退到 index.html。这是经典模板层级图在区块时代的对应版本。

对于每个请求，WordPress 会按顺序查找这些模板 —— 从最具体的开始 —— 并在你主题的 /templates 文件夹中找到的第一个存在的模板处停止。这条链条始终以 index.html 结尾。

首页

站点的首页，无论其设置为显示最新文章还是某个静态页面。

  1. front-page.html
  2. home.html
  3. index.html

无论"设置 → 阅读"中如何选择，front-page.html 始终优先匹配。如果首页是一个静态页面且不存在 front-page.html，则会回退到静态页面链条，而不是 home.html。

博客文章列表页

列出最新文章的页面（即"设置 → 阅读"中的"文章页"）。

  1. home.html
  2. index.html

单篇文章

一篇独立的博客文章。

  1. single-post-{slug}.html
  2. single-post.html
  3. single.html
  4. singular.html
  5. index.html

单条自定义文章类型

某个自定义文章类型的单条内容（例如一本"书"）。

  1. single-{post-type}-{slug}.html
  2. single-{post-type}.html
  3. single.html
  4. singular.html
  5. index.html

对于别名为 "dune" 的 "book" 文章类型：先匹配 single-book-dune.html，再匹配 single-book.html，最后匹配 single.html。

静态页面

一个普通的 WordPress 页面。

  1. page-{slug}.html
  2. page-{id}.html
  3. page.html
  4. singular.html
  5. index.html

使用自定义模板的页面

在编辑器"模板"面板中为其指定了自定义模板的页面。

  1. {custom-template}.html
  2. page-{slug}.html
  3. page-{id}.html
  4. page.html
  5. singular.html
  6. index.html

自定义模板在 theme.json 的 customTemplates 数组中声明，文件位于 /templates 目录下。所指定的模板会优先于整条页面匹配链条。

分类归档

列出某个分类下文章的归档页。

  1. category-{slug}.html
  2. category-{id}.html
  3. category.html
  4. archive.html
  5. index.html

标签归档

列出带有某个标签的文章的归档页。

  1. tag-{slug}.html
  2. tag-{id}.html
  3. tag.html
  4. archive.html
  5. index.html

自定义分类法归档

某个自定义分类法中某个项的归档页。

  1. taxonomy-{taxonomy}-{term}.html
  2. taxonomy-{taxonomy}.html
  3. taxonomy.html
  4. archive.html
  5. index.html

作者归档

某位作者所有文章的归档页。

  1. author-{nicename}.html
  2. author-{id}.html
  3. author.html
  4. archive.html
  5. index.html

日期归档

按年 / 月 / 日划分的归档页。

  1. date.html
  2. archive.html
  3. index.html

文章类型归档

已设置 has_archive 的自定义文章类型的归档列表页。

  1. archive-{post-type}.html
  2. archive.html
  3. index.html

搜索结果

站内搜索的结果页。

  1. search.html
  2. index.html

404（未找到）

当没有内容与该 URL 匹配时显示。

  1. 404.html
  2. index.html

附件页

单个媒体附件对应的页面。

  1. attachment.html
  2. single.html
  3. singular.html
  4. index.html

许多站点会完全禁用附件页（它们内容单薄）。如果你保留它们，这就是其匹配链条。

隐私政策页

在"设置"中被指定为站点隐私政策的页面。

  1. page-privacy-policy.html
  2. privacy-policy.html
  3. page.html
  4. singular.html
  5. index.html

这与经典（PHP）层级结构有何不同

  • 模板是位于 /templates 目录下的 .html 文件，而不是主题根目录下的 .php 文件。这里没有 single.php——它是 single.html。
  • 可复用的区域（页眉、页脚）是位于 /parts 目录下的模板 PART，通过 wp:template-part 区块引用，而不是通过 get_header() / get_footer() 这类 PHP 调用。
  • 这里没有 get_template_part() 链条，也没有 get_header()/get_footer()。组合是在 .html 文件中通过"模板部件"区块完成的。
  • index.html 是必需的。缺少 templates/index.html 的 block theme 不是一个有效的 block theme——它是上面每一条路由的强制性最终回退项。
  • 主题是否为 block theme，是由 templates/index.html 与一个 theme.json 的存在与否决定的，而不是由任何头部标志（header flag）决定。
  • 你可以在站点编辑器（外观 → 编辑器）中编辑上述任意模板，并将改动保存到数据库——保存后的版本会覆盖主题的文件，直到你清除该自定义为止。这常常让那些排查"为什么我改了模板却毫无变化"的人感到意外。