WordPress theme.json 配置手册：区块主题一站式调校

云上的幻象2026-09-187 分钟阅读2,696 字10

100%

一句话结论

WordPress theme.json 是区块主题的总配置中心：用一份 JSON 统管编辑器的「可用选项」与「全局样式」，替代过去散落各处的 add_theme_support 调用。掌握 settings 与 styles 两大区块，就能不写一行 PHP 调校出整套视觉规范。

为什么需要 theme.json

在区块编辑器时代，主题的作者希望「可控」：哪些颜色、字号、间距对用户开放，哪些锁死由主题决定，过去靠一堆 add_theme_support 在 functions.php 里声明，零散且易冲突。theme.json 把这些约定收敛到主题根目录的一个文件里，WordPress 自动据此生成 CSS 变量、编辑器控件和样式表，减少 CSS 体积、避免优先级战争。

当前最新规范是 version 3（WordPress 6.6 引入）。旧版本向后兼容，但新特性只在最新版持续开发，新主题直接写 "version": 3。

文件骨架

一个最小可用的 theme.json 长这样，加上 $schema 还能在编辑器里获得自动补全：

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "customTemplates": {},
  "templateParts": {},
  "patterns": []
}

顶层只有几个键：settings（编辑器能力/预设）、styles（实际样式）、customTemplates、templateParts、patterns。

settings：决定「能做什么」

settings 是配置手册的核心，控制用户可见的选项与默认预设。高频字段：

分组	常用键	作用
color	palette / custom / duotone / gradients / link	配色板、是否允许自定义色、双色调、渐变、链接色
typography	fontSizes / fontFamilies / lineHeight / customFontSize	字号预设、字体族、行高开关
spacing	spacingSizes / units / padding / margin / blockGap	间距刻度、可用单位、内/外边距、块间距
layout	contentSize / wideSize	内容宽度与宽幅对齐宽度
（顶层）	appearanceTools	一键开启边框/链接色/间距/行高等全部 UI 工具

字段取值 true/false 即开关。例如 "color": { "custom": false } 会全局关闭自定义取色器——这正是替代 disable-custom-colors 的现代写法。

styles：决定「长什么样」

styles 把设计直接落到元素上，语法与 settings 对应：

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "name": "墨黑", "slug": "black", "color": "#000000" },
        { "name": "纯白", "slug": "white", "color": "#ffffff" }
      ]
    }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--white)" },
    "typography": { "lineHeight": "1.7" }
  }
}

注意 styles 里直接引用 CSS 变量 --wp--preset--color--white，而不是写死色值——改 palette 即全局联动。

CSS 变量命名规则（必记）

theme.json 生成的自定义属性有固定命名法，调试样式时天天用：

预设：--wp--preset--{类别}--{slug}，如 --wp--preset--color--black
自定义：--wp--custom--{key}--{子key}，如 --wp--custom--line-height--body（驼峰转 kebab-case）
对应类：.has-{slug}-{类别}，如 .has-black-color

per-block 精细控制

settings 和 styles 都支持 blocks 下钻到具体区块，做到「全局一套、个别区块另一套」：

{
  "version": 3,
  "settings": {
    "blocks": {
      "core/post-featured-image": {
        "color": { "customDuotone": false, "custom": false }
      }
    }
  }
}

上例把「特色图片」区块的双色调和自定义色锁死，其余区块保持开放——这是区块主题做品牌管控的常用手法。

settings 和 styles 到底差在哪？

settings 定义「用户能改什么、有哪些预设可选」；styles 定义「主题默认长什么样」。两者都可能设置颜色，但 settings 是给用户的选择项，styles 是主题的出厂默认值，用户选择会覆盖 styles、不覆盖 settings 的结构。