WordPress 模板层级：主题如何决定用哪个模板文件

发布于 作者:

理解 WordPress 如何选择模板文件，是主题开发基础也重要的一环。无论你想修改现有主题，还是从零开始构建，这套规则决定了你的页面会呈现什么样子。

WordPress 通过一套固定的优先级顺序来查找模板文件，这个顺序就是“模板层级”（Template Hierarchy）。简单说：系统根据当前访问的内容类型，按既定顺序在主题目录里找匹配的模板文件，找到一个就用它，找不到就一路回退到 index.php。

核心概念：模板文件是什么

WordPress 主题由一堆 PHP 文件组成，其中专门负责输出页面 HTML 代码的文件就叫模板文件。

常见的几类：

  • header.php —— 全站公用的头部
  • footer.php —— 全站公用的底部
  • sidebar.php —— 侧边栏
  • index.php —— 终的兜底模板，所有页面都能用它来显示
  • single.php —— 单篇文章
  • page.php —— 独立页面
  • archive.php —— 归档页面（文章列表、分类列表等）
  • functions.php —— 主题功能配置文件，不直接输出 HTML

WordPress 如何决定用哪个模板

整个过程分三步：

  1. 分析请求 —— 用户访问的 URL 对应什么类型的内容？是单篇文章、页面、分类列表，还是搜索的结果页？
  2. 按层级找模板 —— WordPress 有一套预设的查找顺序
  3. 命中即停 —— 从具体到通用，找到一个存在的文件就用它

举个例子，用户访问 https://你的域名.com/category/php/，系统判断这是分类归档页，然后按以下顺序找：

text

category-php.php  →  category-{slug}.php
category-6.php    →  category-{id}.php
category.php      →  通用分类模板
archive.php       →  通用归档模板
index.php         →  后兜底

category-php.php 具体，category.php 更通用，index.php 通用。如果 category-php.php 存在就直接用它，否则继续往下找。

子主题的模板覆盖规则

使用子主题时，记住两条核心规则：

  • 子主题里的同名文件会覆盖父主题的同名文件（例如两边都有 category.php，系统用子主题的）
  • 如果子主题只有通用模板（如 category.php），父主题有具体模板（如 category-unicorns.php），系统会用父主题的具体模板

这意味着一件事：子主题能精确覆盖，但也要注意优先级。

各内容类型的模板查找顺序

以下整理了常见的场景，每个场景都列出了 WordPress 的实际查找顺序。

首页（Front Page）

首页有两种模式，取决于后台 设置 → 阅读 的配置。

模式一：首页显示新文章

text

front-page.php → home.php → index.php

模式二：首页显示某个静态页面

text

front-page.php → page-{slug}.php → page-{id}.php → page.php → singular.php → index.php

front-page.php 优先级高，只要它存在，不管哪种模式都会优先使用。

隐私政策页

WordPress 5.0+ 对隐私政策页有专门的处理：

text

privacy-policy.php → 自定义页面模板 → page-{slug}.php → page-{id}.php → page.php → singular.php → index.php

单篇文章

text

single-{post-type}-{slug}.php → single-{post-type}.php → single.php → singular.php → index.php
  • single-post-wordpress.php（如果文章别名是 wordpress）
  • single-post.php（自定义文章类型为 post）
  • single.php
  • singular.php
  • index.php

独立页面

text

自定义页面模板 → page-{slug}.php → page-{id}.php → page.php → singular.php → index.php

自定义页面模板指你在页面编辑后台右侧栏选择的模板，代码里用 get_page_templates() 可获取所有可用选项。

分类页

text

category-{slug}.php → category-{id}.php → category.php → archive.php → index.php

标签页

text

tag-{slug}.php → tag-{id}.php → tag.php → archive.php → index.php

自定义分类法（Custom Taxonomy）

text

taxonomy-{taxonomy}-{term}.php → taxonomy-{taxonomy}.php → taxonomy.php → archive.php → index.php

例如一个叫 book 的分类法，术语是 fiction，系统会依次找：
taxonomy-book-fiction.php → taxonomy-book.php → taxonomy.php → archive.php → index.php

自定义文章类型归档页

text

archive-{post_type}.php → archive.php → index.php

如果文章类型是 product，会先找 archive-product.php。

作者归档页

text

author-{nicename}.php → author-{id}.php → author.php → archive.php → index.php

日期归档页

text

date.php → archive.php → index.php

搜索结果页

text

search.php → index.php

404 页面

text

404.php → index.php

附件页

附件页在 WordPress 6.4 之后默认不再启用，但如果你通过插件启用了，查找顺序如下：

text

{MIME类型}.php → attachment.php → single-attachment-{slug}.php → single.php → singular.php → index.php

例如图片附件会先找 image.php，再找 attachment.php。

嵌入内容（Embed）

当其他网站嵌入你的文章时：

text

embed-{post-type}-{post_format}.php → embed-{post-type}.php → embed.php → wp-includes/theme-compat/embed.php

特殊字符的模板命名

WordPress 4.7 开始支持在模板文件名中使用非 ASCII 字符。如果页面标题是 Hello World 😀，系统会依次找：

text

page-hello-world-😀.php → page-hello-world-%f0%9f%98%80.php → page-6.php → page.php → singular.php

URL 编码版本和非编码版本都有效，系统会优先尝试非编码版本。

经典主题 vs 区块主题

本文讨论的内容以经典主题为主，模板文件后缀是 .php。区块主题沿用了同样的层级逻辑，只是文件名后缀变成了 .html。

不论哪种主题类型，优先级顺序完全一致。

总结

模板层级的核心逻辑可以概括为三句话：

  1. 从具体到通用 —— WordPress 依次查找越来越通用的模板文件
  2. 命中即停 —— 找到一个存在的文件就直接使用
  3. 永不失败 —— 再差的主题也有 index.php 兜底

开发主题时可以对照这些顺序来规划文件结构。修改某个页面不想动全局？就创建更具体的模板文件。想让某些分类长得不一样？用 category-slug.php 就能实现。