WordPress 主题模板文件完全指南

发布于 作者:

对于刚开始接触 WordPress 主题开发的朋友来说，”模板”这个词往往让人困惑——它到底指的是什么？是 PHP 文件？HTML 文件？还是页面布局？其实，在 WordPress 的里，模板有着多层含义。这篇文章将为你理清模板文件的概念体系，从基础的 index.php 到特定页面的专属模板，带你了解 WordPress 是如何决定使用哪个文件来展示内容的。我们会绕开那些晦涩的官方术语，用更直白的方式解释模板层级、页面模板、模板标签这些概念，让你对 WordPress 主题的运作方式有一个清晰的认识。

基础概念：到底什么是模板？

在 WordPress 主题开发中，”模板”这个词会在不同场景下出现，含义也略有不同：

  • 模板文件：就是主题文件夹里的那些 .php 或 .html 文件，它们负责生成你在浏览器里看到的页面。
  • 模板层级：WordPress 根据当前访问的内容类型，按优先级决定使用哪个模板文件的一套规则。
  • 页面模板：专门给页面、文章或自定义内容类型准备的模板，用来改变特定页面的外观。

在经典主题（ classic themes ）里，你还会遇到模板标签——它们是 WordPress 内置的 PHP 函数，比如 the_title() 用来显示标题，the_content() 用来显示正文。而在区块主题（ block themes ）里，这些功能由区块（ blocks ）替代。

模板文件长什么样？

WordPress 主题由一堆模板文件构成：

  • 经典主题：模板文件是 .php 文件，里面混合了 HTML、模板标签（PHP函数）和 PHP 代码。
  • 区块主题：模板文件是 .html 文件，里面是代表区块的 HTML 标记。

你可以用模板文件来控制网站不同部分的布局和设计。比如，你会用一个头部模板（ header template ）或模板部件（ template part ）来创建页头。

当有人访问你网站上的某个页面时，WordPress 会根据请求内容来决定加载哪个模板文件。这个选择过程就是”模板层级”（ Template Hierarchy ）——它是一套规则，决定了在特定情况下用哪个模板。服务器解析完模板文件里的代码后，会把生成的 HTML 返回给访客。

index.php：所有模板的底线

重要的模板文件是 index.php（经典主题）或 index.html（区块主题）。它是一个”万能兜底”模板——当模板层级找不到更具体的模板时，就会用这个。虽然一个主题理论上只需要 index 这一个模板就能运转，但大多数主题都会准备多个模板，用来应对不同的内容类型和场景。

模板部件（ Template Parts ）

模板部件是被其他模板文件包含进来的一段模板代码，比如网站的头部。它可以在多个模板中重复使用，省去重复编写相同代码的麻烦。

常见的模板部件有：

  • header.php 或 header.html —— 生成网站头部
  • footer.php 或 footer.html —— 生成底部
  • sidebar.php 或 sidebar.html —— 生成侧边栏

除了这几个”特殊”的模板部件（WordPress 对它们有特定的识别规则），你完全可以创建任意数量的模板部件，然后把它们引入到其他模板文件中。在区块主题中，模板部件必须放在 parts 文件夹里。

常见的 WordPress 模板文件清单

下面列出的是一些 WordPress 能识别的核心模板文件：

style.css（必需）

主题的主样式表，所有主题都必须有。它里面还包含了主题的信息头——就是告诉 WordPress 这个主题叫什么名字、作者是谁、版本号多少的那段注释。

rtl.css

当网站语言是从右向左书写时（比如阿拉伯语），WordPress 会自动加载这个样式表。

front-page.php / front-page.html

如果网站设置了静态首页，且主题里有这个文件，WordPress 会优先用它来显示首页——不管你在后台”设置 → 阅读”里怎么配置。

home.php / home.html

默认的首页模板。如果你没有设置静态首页，WordPress 会用这个模板来展示新的文章列表。

singular.php / singular.html

“单一内容”的兜底模板。当 single.php（单篇文章）或 page.php（页面）找不到时，WordPress 会尝试用 singular.php。如果连这个都没有，就只好用 index.php 了。

single.php / single.html

用来显示单篇文章。

single-{post-type}.php / single-{post-type}.html

用来显示自定义内容类型的单篇文章。比如你创建了一个叫 book 的内容类型，那么 single-book.php 就会被用来展示单本书的详情。

page.php / page.html

用来显示单个页面（WordPress 内置的”页面”内容类型）。

page-{slug}.php / page-{slug}.html

用来显示特定的某个页面。比如你有一个页面的别名（slug）是 about，那么 page-about.php 就会被优先使用。

category.php / category.html

用来显示按分类归档的文章列表。

tag.php / tag.html

用来显示按标签归档的文章列表。

taxonomy.php / taxonomy.html

用来显示自定义分类法（ custom taxonomy ）的归档页面。

author.php / author.html

用来显示作者归档页面——列出某个作者发表的所有文章。

date.php / date.html

按日期归档页面。比如你访问 http://example.com/blog/2024/、http://example.com/blog/2024/05/ 之类的链接时，就会用到这个模板。

archive.php / archive.html

归档模板的兜底方案。当按分类、作者、日期等方式归档时，如果找不到更具体的模板（比如 category.php 或 author.php），WordPress 会退而求其次使用 archive.php。

search.php / search.html

显示搜索结果。

attachment.php / attachment.html

用来显示单个附件，比如图片、PDF 或其他媒体文件。

image.php / image.html

attachment.php 的更具体版本，专门用来显示图片附件。如果找不到 image.php，WordPress 会尝试 attachment.php。

404.php / 404.html

当 WordPress 找不到匹配的内容时，就会用这个模板来展示”页面未找到”。

comments.php（仅经典主题）

用来显示评论区域。在区块主题中，评论功能通过区块实现。

如何在模板文件中组织代码？

经典主题：模板标签的用法

在经典主题的 PHP 模板里，你可以用模板标签来动态获取数据、引入其他文件，或者给网站增加各种功能。

比如在 index.php 里，你可以用这些函数把其他部分包含进来：

php

// 引入头部文件
<?php get_header(); ?>

// 引入侧边栏
<?php get_sidebar(); ?>

// 引入底部
<?php get_footer(); ?>

// 引入搜索表单
<?php get_search_form(); ?>

// 引入自定义模板片段
<?php get_template_part( 'featured-content' ); ?>

get_template_part() 是一个很灵活的函数——你可以用它来复用任何一段模板代码。比如你有个 featured-content.php 文件，用 get_template_part( 'featured-content' ) 就能把它引入进来。

在链接样式表、JavaScript 文件或者主题内的其他资源时，不要直接写死路径。WordPress 提供了一些专门的函数来处理这类问题，你可以参考官方文档中”Linking Theme Files & Directories”部分的说明。

区块主题：用区块标记替代 PHP 函数

在区块主题中，模板部件就是区块。要在模板文件里包含头部或底部，直接用区块标记：

html

<!-- wp:template-part {"slug":"header"} /-->

<!-- 页面主体内容放这里 -->

<!-- wp:template-part {"slug":"footer"} /-->

要显示搜索框，用搜索区块：

html

<!-- wp:search {"label":"搜索","buttonText":"搜索"} /-->

总结

理解 WordPress 的模板系统是主题开发的一步。记住几个关键点：

  • index.php / index.html 是所有模板的底线，必须有。
  • 模板层级决定了用哪个模板——规则是”越具体越优先”。
  • 模板部件（ header、footer、sidebar 等）让你能够复用代码，保持主题整洁。
  • 经典主题用 PHP 函数（模板标签）来动态获取数据；区块主题用 HTML 标记（区块）来实现同样的功能。

实际开发时，你可以从一个只有 style.css 和 index.php 的简主题开始，然后根据需求逐步添加更多模板文件。熟悉了这些基础文件的作用和优先级后，你就能按照自己的想法控制网站的每个角落了。