WordPress 经典主题文件结构：从零开始整理你的代码

对于任何刚开始接触WordPress主题开发的朋友来说，面对一堆PHP文件、CSS样式表和JavaScript脚本，常见的反应就是“我该从哪里下手”。官方文档说技术上只要两个文件就能跑起一个主题，但现实中，哪怕是一个简单的内容展示型网站，你也需要处理头部、底部、侧边栏、文章列表、单页内容等等。如果不从一开始就建立起清晰的文件组织习惯，随着项目复杂度的增加，混乱几乎是必然的。

这篇文章将带你直接看一个经过实战检验的经典主题范例——WordPress默认的Twenty Seventeen。我会告诉你为什么它要把不同类型的文件放在不同的文件夹里，哪些是WordPress能够识别的“约定俗成”，哪些是你完全可以自由发挥的。读完这篇笔记，你至少能看懂任何一个标准WordPress主题的目录结构，并为自己下一个主题选择一个合理的组织方式。

---

核心规则：仅有的两个“强制”文件

在WordPress经典主题（即使用PHP模板文件的主题）中，技术上的低要求只有两个文件：

• style.css：这个文件必须放在主题的根目录下，不能放在任何子文件夹里。它不仅仅是CSS样式表，它的文件头注释部分还包含了主题的名称、作者、版本、描述等元数据，WordPress就是通过读取这个文件头来识别和显示主题信息的。
• index.php：这是整个主题的“万能后备”模板文件。当WordPress找不到更具体的模板文件（比如找不到single.php来显示单篇文章，或者找不到page.php来显示页面）时，就会回退到index.php来渲染页面。

除此以外，其他所有文件和文件夹的组织方式都是自由的。但这恰恰是初学者容易迷失的地方——自由意味着需要自己建立规范。

参考典范：Twenty Seventeen 目录结构解析

WordPress默认自带的Twenty系列主题，一直都是佳实践的参考对象。我们来看一下Twenty Seventeen的目录结构，这是一个非常典型的经典主题布局：

text

.
├── assets/                  # 静态资源文件夹
│   ├── css/                # 样式文件（除了style.css）
│   ├── images/             # 图片资源
│   └── js/                 # JavaScript脚本
├── inc/                     # 功能函数集合
├── template-parts/          # 可复用的模板片段
│   ├── footer/             # 底部相关片段
│   ├── header/             # 头部相关片段
│   ├── navigation/         # 导航菜单片段
│   ├── page/               # 页面内容片段
│   └── post/               # 文章内容片段
├── 404.php                  # 404错误页面模板
├── archive.php              # 归档页面模板
├── comments.php             # 评论区域模板
├── footer.php               # 全局底部模板
├── front-page.php           # 静态首页模板
├── functions.php            # 主题初始化与功能配置
├── header.php               # 全局头部模板
├── index.php                # 主索引/默认模板
├── page.php                 # 单页面模板
├── README.txt               # 说明文档
├── rtl.css                  # 从右向左文字方向的支持样式
├── screenshot.png           # 主题预览截图
├── search.php               # 搜索结果页模板
├── searchform.php           # 搜索框表单模板
├── sidebar.php              # 侧边栏模板
├── single.php               # 单篇文章模板
└── style.css                # 主样式表（含主题信息头）

各目录的职责边界

根目录下的模板文件

根目录下放置的是WordPress能够直接识别和调用的模板文件。这些文件对应着不同类型的页面请求：

• header.php 和 footer.php：分别控制整个网站统一的头部和底部区域。几乎所有页面都会通过 get_header() 和 get_footer() 函数来调用它们。
• sidebar.php：侧边栏内容，通过 get_sidebar() 调用。如果你的主题不需要侧边栏，这个文件可以省略。
• single.php：当访问某篇独立文章时，WordPress会优先使用这个模板。
• page.php：当访问“页面”这种内容类型时使用。
• archive.php：用于显示文章归档列表，包括分类、标签、日期归档等。
• search.php：搜索结果列表页。
• 404.php：当用户访问不存在的URL时显示。
• front-page.php：当你在后台设置了一个静态页面作为首页时，这个模板会生效。如果不存在，则会使用 home.php 或 index.php。
• comments.php：评论区域的HTML结构和逻辑通常独立出来，方便在 single.php 或 page.php 中通过 comments_template() 调用。

注意：index.php 作为后的回退模板，优先级低。当其他更具体的模板文件都不存在时，WordPress才会使用它。

assets 资源文件夹

这是一个约定俗成的命名，用于存放所有前端静态资源。在这个目录下，通常还会按文件类型进一步划分：

• css/：这里存放除了根目录 style.css 以外的所有样式文件。比如你可能会把首页样式、文章页样式、响应式样式等拆分到不同的文件中，然后通过 wp_enqueue_style() 按需加载。根目录下的 style.css 通常只保留主题信息头，并 @import 或通过函数加载 assets/css/ 里的主要样式。
• js/：存放所有JavaScript文件。同样需要通过 wp_enqueue_script() 来正确地引入，而不是硬编码在HTML里。
• images/：存放主题用到的图片素材，比如背景图、图标、Logo等。

inc 功能函数文件夹

inc/ 是“include”的缩写，用于存放被 functions.php 引用的功能模块文件。随着主题功能增多，functions.php 会迅速膨胀，将不同功能的代码拆分到 inc/ 目录下的独立文件中，是一种非常健康的组织方式。

举个例子，你可以创建一个 inc/customizer.php 文件来存放所有与WordPress自定义器相关的设置代码，然后在 functions.php 中这样引用：

php

// 在 functions.php 中加载自定义器功能
require_once get_template_directory() . '/inc/customizer.php';

template-parts 模板片段文件夹

这是一个非常重要的组织方式，它将可复用的模板部分按功能或位置归类：

• header/：存放头部可能用到的不同样式或结构的片段，比如一种用于首页的头部，一种用于内页的头部。
• footer/：同理，底部的不同变体。
• navigation/：导航菜单的不同实现方式。
• page/：页面内容的不同布局，比如全宽页面、带侧边栏页面等。
• post/：文章内容的不同展示格式，比如标准格式、图片格式、视频格式等。

在模板文件中，你可以通过 get_template_part() 函数来调用这些片段。比如在 single.php 中调用文章内容片段：

php

// 调用 template-parts/post/content.php 文件
get_template_part( 'template-parts/post/content', 'single' );

这个函数的二个参数允许你指定一个“后缀”，它会去寻找 content-single.php 文件，如果找不到，则回退到 content.php。这为布局的灵活性提供了大的便利。

两个特殊文件夹的说明

• languages 语言文件夹：如果你希望你的主题能够被翻译成其他语言，就需要使用WordPress的国际化（i18n）功能。通常的做法是在这个文件夹里放置一个 .pot 模板文件以及编译好的 .mo 文件。虽然默认名称是 languages，你可以在 functions.php 中通过 load_theme_textdomain() 函数来指定其他路径，但为了保持一致性，建议不要随意更改。
• Block themes 的差异：这里需要特别说明，以上所有内容都是针对经典主题（使用PHP模板的传统方式）。如果你使用的是基于区块编辑器（Gutenberg）的区块主题，目录结构有完全不同的强制要求：模板文件必须放在 /templates 文件夹，模板片段必须放在 /parts 文件夹。本篇文章仅讨论经典主题，区块主题不在讨论范围内。

总结

组织一个WordPress经典主题的文件结构，核心思路可以概括为三点：

• 根目录保持清爽：只放置 style.css、index.php 以及WordPress能够直接识别的模板文件（如 header.php、footer.php、single.php、page.php 等）。
• 功能模块分离：利用 assets/ 管理前端资源，利用 inc/ 管理PHP功能函数，利用 template-parts/ 管理可复用的HTML和PHP混合片段。
• 遵循惯例：虽然只有 style.css 和 index.php 是强制的，但参考官方默认主题的结构能够让其他开发者（甚至未来的自己）更快地理解你的代码，减少沟通和维护成本。

记住，良好的文件结构不是给WordPress看的，而是给人看的。一个清晰、有逻辑的目录，比任何技术文档都更能说明一个主题的开发质量。