WordPress 主题负责站点的展示层。现在需要先区分经典主题与区块主题：两者都使用模板层级，但文件类型、编辑方式和最小结构不同。把所有 PHP 功能都堆进 functions.php 的做法也需要重新审视。
经典主题
最小可运行结构：
my-classic-theme/
├── style.css
└── index.php
style.css 根目录文件用于注册主题信息，index.php 是最终回退模板。常见项目还会包含：
my-classic-theme/
├── assets/
│ ├── css/
│ ├── images/
│ └── js/
├── inc/
├── template-parts/
├── 404.php
├── archive.php
├── footer.php
├── front-page.php
├── functions.php
├── header.php
├── page.php
├── search.php
├── single.php
├── style.css
└── index.php
WordPress 按模板层级寻找最具体的文件，找不到时逐级回退到 index.php。不是每个文件都必需，也不应复制相同 Loop 到所有模板。
区块主题
最小结构：
my-block-theme/
├── style.css
└── templates/
└── index.html
实际项目通常还包括：
my-block-theme/
├── parts/
├── patterns/
├── styles/
├── templates/
├── functions.php
├── style.css
└── theme.json
theme.json 统一配置设计 token、编辑器能力和全局样式；templates/*.html 与 parts/*.html 使用区块标记。区块主题允许在站点编辑器中修改模板，因此还要规划代码版本和数据库中用户自定义模板之间的关系。
style.css 不是普通注释文件
/*
Theme Name: Acme Site
Description: Acme 企业站主题
Version: 1.0.0
Text Domain: acme-site
Requires at least: 6.5
Requires PHP: 8.1
License: GNU General Public License v2 or later
*/
Requires at least 和 Requires PHP 必须来自真实测试基线，不能照抄示例。公开发布主题还需要遵守 WordPress.org 的更多元数据和审查要求。
functions.php 的边界
适合放在主题中的内容：
- 注册主题支持、菜单位置和图片尺寸。
- 加载主题 CSS 与 JavaScript。
- 注册与展示紧密相关的区块样式、区块变体和模板辅助函数。
更适合站点专用插件的内容：
- 自定义文章类型与分类法。
- 订单、表单、同步任务和外部 API。
- 与当前主题无关的权限与业务规则。
- 切换主题后仍必须保留的数据能力。
functions.php 会在主题启用时自动加载，但它不是一个无边界的全局工具箱。可以拆到 inc/，不过拆文件只是组织方式，真正要解决的是职责、命名空间、依赖和测试。
需要临时管理小段代码时，可以评估 Code Snippets 这类工具；生产使用仍要审查权限、备份、错误恢复与插件维护状态。
资源加载
不要在 header.php 里硬编码多个 <script>。使用 wp_enqueue_scripts、wp_enqueue_style() 和 wp_enqueue_script()，声明依赖和版本，并只在需要的页面加载大资源。
建议的开发检查
- 开启
WP_DEBUG的开发环境，但不要向公网访客显示错误。 - 使用 WordPress Coding Standards、PHP 静态分析和前端 lint。
- 验证模板层级、404、搜索、分页、无内容状态和评论。
- 检查键盘导航、标题层级、语言属性和图片替代文本。
- 在暂存环境验证 WordPress、PHP 和关键插件升级。
- 不直接修改父主题或 WordPress Core。
官方参考：Theme Handbook、Theme Structure、Classic Template Hierarchy。