WordPress 块主题文件结构：从零开始认识主题骨架
如果你是 WordPress 新手，打开一个主题文件夹时可能会被各种文件和文件夹搞懵。这很正常——我一次看到 functions.php 和 style.css 同时存在时，也不知道该动哪个。
简单来说，WordPress 主题就是一堆文件的集合，这些文件共同决定了一个网站长什么样、能做什么。块主题（Block Theme）是 WordPress 目前主推的主题类型，它有一套约定的文件结构。掌握这套结构，你就知道该去哪里改代码、加功能。
这篇文章会带你认识块主题的“骨架”：哪些文件是必须的，哪些是可选的，每个文件夹是干什么用的。不需要你记住所有东西，有个大致印象就行——等真正动手改主题时，知道去哪里翻资料比死记硬背重要得多。
一、核心文件：两个必须有的文件
任何一个能被 WordPress 识别的块主题，至少需要这两个文件：
1. style.css——主题的“身份证”
这个文件有两个作用：一是告诉 WordPress 你的主题叫什么、作者是谁、版本号多少；二是放一些全局 CSS 样式。
打开一个 style.css，文件头部通常长这样：
css
/* Theme Name: 我的主题 Theme URI: https://example.com Author: 你的名字 Author URI: https://example.com Description: 这是一个简单的块主题 Requires at least: 6.0 Tested up to: 6.5 Requires PHP: 7.4 Version: 1.0.0 License: GPL v2 or later Text Domain: my-theme */
这些注释不是随便写写的——WordPress 后台会读取它们，显示在“外观 > 主题”的卡片上。下面的 CSS 代码就是正常的样式表了。
2. templates/index.html——兜底模板
这个文件是主题的“后防线”。当 WordPress 找不到任何更具体的模板（比如页面模板、文章模板）来显示当前内容时，就会用 index.html。
在块主题里，模板文件是用 HTML 写的，里面包裹着 WordPress 块（Block）的标记。一个简单的 index.html 可能是这样的：
html
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:group -->
<div class="wp-block-group">
<!-- wp:post-content /-->
</div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer"} /-->
注意这里的 <!-- wp:... --> 是块标记，不是普通的 HTML 注释。WordPress 解析器会识别这些标记并渲染对应的块。
二、标准文件夹：WordPress 约定的存放位置
除了上述两个必需文件，下面这几个文件夹是 WordPress 专门预留的，放对应类型的内容：
templates/——整页模板
存放你主题里所有完整的页面模板。除了 index.html，常见模板还包括：
404.html：404 错误页面archive.html：归档页面（分类、标签、日期归档等）singular.html：单篇文章/页面的通用模板page.html：单独的页面模板single.html：单独的文章模板
WordPress 有一套“模板层级”规则：访问一个页面时，它会按顺序查找匹配的模板文件。比如访问一篇普通文章，WordPress 会先找 single-post.html，没有就找 single.html，再没有就找 singular.html，后才是 index.html。
parts/——模板零件
模板零件就是可以重复使用的小碎片，通常用来做头部、底部、侧边栏。你可以把 parts/ 看作一个零部件仓库，每个零件都是一个独立的 HTML 文件。
比如 parts/header.html 可能包含网站标志、导航菜单；parts/footer.html 包含版权信息和友情链接。然后在 templates/index.html 里用 <!-- wp:template-part {"slug":"header"} /--> 把它“拉”进来。
这样做的好处是：改一处 header.html，所有引用它的模板都会更新，不用逐个页面修改。
patterns/——块模式
块模式是由多个块组合成的布局模板。用户在编辑页面时，可以从“块模式”面板里一键插入这些预制好的布局，比如“三栏图文混排”“带背景的号召性语句”等。
每个 patterns/ 文件夹里的 PHP 文件会返回一个数组或一段块标记，WordPress 会自动注册它们。示例：
php
<?php
return array(
'title' => '三栏卡片布局',
'description' => '展示三个并排的内容卡片',
'content' => '<!-- wp:columns -->...<!-- /wp:columns -->',
);
styles/——样式变体
存放 JSON 格式的样式变化文件。你可以理解为“同一套主题的不同皮肤”——切换样式变体会改变全局颜色、字体等视觉属性，而不影响内容结构。
一个 styles/dark.json 文件可能长这样：
json
{
"version": 3,
"settings": {
"color": {
"palette": [
{
"slug": "background",
"color": "#1a1a1a",
"name": "背景色"
}
]
}
}
}
三、其他常见文件和文件夹
theme.json——全局设置中心
这是块主题重要的配置文件之一。你可以在这里控制：
- 颜色调色板
- 字体大小预设
- 间距（margin/padding）选项
- 区块的默认样式
- 是否启用某些功能
WordPress 的后台“样式”界面，很多选项其实就是这个文件的图形化操作界面。
functions.php——PHP 扩展点
当主题需要 PHP 来添加额外功能时，这个文件就派上用场了。比如注册自定义块、添加额外的 CSS 类、修改某些默认行为。
注意：块主题强调“用配置代替代码”，所以 functions.php 的作用比传统主题小了很多。能用 theme.json 搞定的，尽量别写 PHP。
php
// 一个简单的示例：为文章添加自定义类
add_filter('body_class', function($classes) {
if (is_single()) {
$classes[] = 'single-post-style';
}
return $classes;
});
screenshot.png——主题预览图
尺寸为 1200×900 的图片，WordPress 后台和主题目录会用这张图来展示你的主题。支持 PNG 和 JPG 格式。
README.txt——说明文档
提交到 WordPress 官方主题目录时必须要有的文件。给用户看的，写清楚主题特点、安装方式、版权信息等。WordPress 本身不会执行这个文件。
四、开发者常用的附加文件和文件夹
这部分内容对于普通建站用户来说可以先跳过，如果你是开发者或想深入，了解一下没坏处。
assets/——静态资源
存放 CSS、JavaScript、图片等前端资源。有些主题作者也会叫 resources/ 或 public/。
inc/——PHP 辅助文件
放自定义 PHP 类或函数库，保持 functions.php 整洁。常见别名有 includes/ 或 src/。
版本控制和构建工具文件
.gitignore/.gitattributes：Git 版本控制相关.editorconfig：统一编辑器代码风格package.json：Node.js 项目配置，常用于定义构建流程CHANGELOG.md：版本更新日志LICENSE.md：许可证声明（提交官方主题目录必须用 GPL v2 或更高版本）
这些文件跟 WordPress 运行没有直接关系，但如果你在团队协作或者维护一个长期项目，它们会让工作更规范。
总结
记住这几条，你就掌握了块主题文件结构的精髓：
- 三个核心位置：
style.css（主题信息）、templates/index.html（兜底模板）、theme.json（全局配置）。其中前两个是必须的。 - 四个标准文件夹：
templates/放整页模板，parts/放可复用零件，patterns/放块组合模板，styles/放样式变体。 - 按需增加：静态资源放
assets/，PHP 工具代码放inc/。不是非要有的，别一开始就建一堆空文件夹。 - php 和 html 并存：块主题用 HTML 文件定义内容结构，用
functions.php和theme.json处理逻辑和配置。各司其职，别弄混了。 - 先读懂，再动手：改代码之前，花十分钟把主题目录过一遍，知道每个文件是干什么的。遇到不认识的，去查 WordPress 官方文档或看社区里成熟的主题是怎么处理的。
把主题想象成一座房子的设计图纸。style.css 是封面说明，templates/ 是每层楼的平面图，parts/ 是门窗这些标准件，theme.json 是装修配色方案。图纸清晰了，施工才不慌乱。