主题体系与模板层级

这一课你将能做到

1. 画出模板层级（Template Hierarchy）的匹配顺序，看到任意 URL 就能说出它会加载哪个模板文件
2. 创建规范的子主题，安全地定制 Twenty Twenty-Five 等开箱主题而不怕升级覆盖
3. 用 theme.json 给站点配置全局色板、字号与间距，并理解它与站点编辑器的关系

为什么要学

主题是 WordPress 的「路由 + 视图」层：URL 进来，WP 按模板层级决定用哪个 PHP 文件渲染。不改主题就无法定制任何前台页面；不懂得用子主题，一次主题升级就能把你的改动全部抹掉。

人话：模板层级像 Spring MVC 的路由分发——同一个「/分类/Java」请求，WP 会按优先级去找 category-java.php → category.php → archive.php → index.php，找到第一个就停。会读这条链，你就拿到了前台排障的地图。

先建立图像

模板匹配的决策树（自上而下，命中即止）：

首页        front-page.php → home.php → index.php
单篇文章    single-post.php → single.php → singular.php → index.php
静态页面    page-{slug}.php → page-{id}.php → page.php → singular.php → index.php
分类归档    category-{slug}.php → category.php → archive.php → index.php
搜索结果    search.php → index.php
404         404.php → index.php

底线规则：任何主题必须有 index.php，它是所有请求的兜底。

跟着做

步骤 1：装一个 6.x 开箱主题

后台「外观 → 主题 → 安装新主题」，搜索安装 Twenty Twenty-Five（WP 6.7 起的默认区块主题）并启用。进「外观 → 编辑器」感受一下：整站页头、页脚、模板都能在浏览器里改——这就是区块主题 + 全站编辑（FSE）。

步骤 2：创建子主题骨架

在 wp-content/themes/ 下新建 tt25-child/，两个文件：

/* style.css —— 子主题的身份证，头部注释不能少 */
/*
Theme Name:   TT25 Child
Template:     twentytwentyfive
Description:  课程站子主题示例
Version:      1.0
Requires PHP: 8.2
*/

<?php
// functions.php
add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'tt25-child',
        get_stylesheet_uri(),          // 子主题 style.css
        array( 'tt25-style' ),         // 依赖父主题样式句柄
        wp_get_theme()->get( 'Version' )
    );
} );

Template: 的值必须是父主题目录名（区分大小写）。后台启用「TT25 Child」。

步骤 3：用模板覆盖验证层级

在子主题里新建 single.php：

<?php get_header(); ?>
<main>
    <p style="color:red">我来自子主题 single.php</p>
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
        <h1><?php the_title(); ?></h1>
        <div><?php the_content(); ?></div>
    <?php endwhile; endif; ?>
</main>
<?php get_footer(); ?>

打开任意一篇文章，看到红色提示即证明：子主题同名模板优先于父主题。删掉这个文件，页面自动回落到父主题——层级规则亲测一遍，比背十遍都有用。

步骤 4：theme.json 全局样式

子主题根目录新建 theme.json：

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "color": {
            "palette": [
                { "slug": "brand", "color": "#1a5fb4", "name": "Brand" }
            ]
        },
        "typography": {
            "fontSizes": [
                { "slug": "lg", "size": "24px", "name": "Large" }
            ]
        }
    },
    "styles": {
        "color": { "background": "#fafafa", "text": "#1e1e1e" }
    }
}

刷新后台「外观 → 编辑器」：色板里出现 Brand，正文底色生效。区块主题的视觉配置以 theme.json 为唯一来源，站点编辑器里的修改最终也同步回它。

讲清楚要点

1. 模板层级 = WP 的视图路由：它比任何主题的代码都优先。排障第一步永远是「这个 URL 落在哪个模板」而不是「改哪段 CSS」。
2. 经典主题 vs 区块主题的分界：经典主题靠 PHP 模板 + The Loop 手写结构；区块主题的模板是 HTML 文件，内容是区块标记（<!-- wp:... -->），全靠站点编辑器可视化调整。 Twenty Twenty-Five 属于后者，但 PHP 模板知识依然是兜底能力。
3. 子主题三件套：style.css（含 Template: 头）、functions.php（可选，加载脚本用）、theme.json（可选）。子主题的 functions.php 先于父主题加载。
4. theme.json 的本质：声明式样式系统——你配 slug，WP 自动生成 CSS 自定义属性（如 --wp--preset--color--brand），区块和前端共用一套变量。
5. 结构复用：get_template_part( 'template-parts/card', get_post_type() ) 把卡片拆成可复用组件，第二个参数让 WP 自动找 card-course.php 这类变体。

你可能会懵的地方

• 区块主题还要学 PHP 模板吗？ 要。大量存量站点是经典主题；区块主题的动态逻辑、条件输出仍要 PHP；面试也常以层级规则考基础。

• front-page.php 和 home.php 到底谁管首页？ front-page.php 是站点首页（无论显示静态页还是文章列表）；home.php 只在首页选择「显示最新文章」时用。设置「静态页做首页」后，文章列表页找 home.php。

• 子主题能覆盖父主题的函数吗？ functions.php 不行（先加载完父主题的），但父主题若用 function_exists 包裹的「可插拔函数」或把函数挂在 hook 上，子主题可以 remove_action 后重挂。

• page-{slug}.php 和 page.php 冲突时用哪个？ 专属模板优先：page-about.php 只服务别名为 about 的页面，page.php 是普通页面兜底。

• 站点编辑器改的东西存在哪？ 存数据库（wp_posts 里的 wp_template 类型），会覆盖主题文件里的同名模板；导出后可落回主题目录。

错法对照

错法	问题	正解
直接改父主题文件	升级即全部丢失	建子主题，覆盖同名模板
style.css 忘写 Template:	子主题无法关联父主题	头部注释补全并核对目录名
用 @import 引父主题样式	阻塞加载且顺序不可控	wp_enqueue_style 声明依赖
自定义文件命名 page-1.php 想按 ID 匹配	不生效	ID 模板格式是 page-{id}.php，或用 slug
改了模板没反应就乱清缓存	根因是文件放错层级	先核对匹配链，再谈缓存

卡点急救

1. 子主题在后台不出现：style.css 没在主题根目录，或 Template: 值与父主题目录名不一致。
2. 激活子主题后白屏：functions.php 语法错误，看 wp-content/debug.log 定位行号。
3. 样式全乱了：子主题样式句柄写对但没声明依赖父主题样式，或父主题句柄名猜错——用浏览器 F12 → Network 确认父主题 CSS 的 id/handle。

面试常问

• 请求 /category/java/ 时模板加载顺序？ category-java.php（若存在）→ category.php → archive.php → index.php。可继续追问 taxonomy.php 与 archive.php 的层级关系。

• 经典主题与区块主题的区别？ 经典主题用 PHP 模板 + Loop 渲染；区块主题用 HTML 模板 + 区块标记，配合 theme.json 与站点编辑器实现全站可视化编辑。

• 为什么生产项目必须用子主题？ 隔离定制与上游更新：升级父主题不会覆盖子主题内容，同时保留继承父主题全部功能的能力。

自测三问

1. 写出「别名为 about 的页面」的完整模板匹配链。
2. 子主题的 style.css 头部注释里，哪个字段决定它继承谁？
3. theme.json 的 slug 生成的 CSS 变量叫什么？举一例。

小结一句话

模板层级是 WordPress 前台的「路由表」，子主题是安全定制的唯一正道，theme.json 是区块主题的样式单一来源——三者合起来，你就掌握了 WP 展示层的骨架。

延伸

• 模板层级官方文档
• theme.json 参考手册
• 下一课：Gutenberg 区块开发——从 block.json 开始写你自己的区块。