WordPress主题开发：彻底搞懂theme.json

发布于2023年5月18日2026年7月30日作者:XQcms

如果你正在开发WordPress区块主题，theme.json就是你绕不开的核心文件。它就像一个控制面板，让你集中管理主题的全局设置和样式——从启用哪些编辑器功能，到定义配色方案、字体大小，再到注册模板和模板部件，统统都能在这里搞定。

很多人一开始接触theme.json，被它那层层嵌套的JSON结构吓到了。其实没那么复杂。这篇文章我会从基础的概念讲起，告诉你这个文件到底是干什么的、怎么写、以及它在整个WordPress系统中的优先级关系。读完你就能看懂官方的theme.json文档，也知道怎么动手给自己的主题写配置文件了。

什么是theme.json？

简单说，theme.json是WordPress区块主题的标准配置文件。WordPress会自动识别你主题根目录下的这个文件，读取里面的配置来决定：

编辑器里哪些功能开关是打开的（比如是否允许用户调整内边距、外边距）
主题提供哪些颜色、渐变、阴影可供选择
字体相关的设置（字体家族、字号等）
自定义CSS属性的生成
自定义模板和模板部件的注册

注意：虽然技术上区块主题可以不包含theme.json文件，但实际开发中几乎一定会用到它。没有这个文件，你的主题在站点编辑器里的可定制性会大打折扣。

来看一个简的theme.json示例，它只做了一件事：开启外观工具（appearanceTools）。

json

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"appearanceTools": true
	}
}

就这几行代码，你就在站点编辑器里解锁了一大批样式控制选项，包括边框、间距、排版等。theme.json的威力可见一斑。

theme.json 的核心结构

一个完整的theme.json文件，顶层有这么几个关键属性：

json

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

属性	作用
`$schema`	告诉编辑器用哪个JSON规范来验证你的文件。配上这个，你在VS Code里写`theme.json`时就会有智能提示和报错提醒。
`version`	当前使用的schema版本号。目前新稳定版是`2`。不确定用哪个版本时，去查阅官方theme.json参考手册。
`settings`	控制编辑器里各种功能的开关，定义颜色调色板、字号梯度、间距预设等。
`styles`	实际给网站和区块施加的样式——背景色、字体大小、边框、自定义CSS等。
`customTemplates`	注册你在`/templates`文件夹里自定义的模板，告诉WordPress这些模板的标题和用途。
`templateParts`	注册你在`/parts`文件夹里的模板部件，并指定它们属于哪个区域（比如页眉、页脚）。
`patterns`	一个数组，填入你想从官方Pattern目录里注册的区块模式（也就是现成的布局模板）的slug。

注意：实际开发中，settings和styles是你常打交道的地方，它们俩共同决定了主题在站点编辑器里的表现。

配置的优先级：谁说了算？

theme.json的配置不是孤立的。在WordPress系统里，样式和设置的来源有好几个层级，后加载的会覆盖先加载的。理解这个顺序，能帮你避免“明明在theme.json里写了，前台却没生效”的困惑。

从低优先级到高优先级依次是：

WordPress核心的theme.json
WordPress自己带了一份默认的theme.json，定义了系统级的基准设置。比如默认启用的功能、默认的颜色板等。
你的主题（父主题）的theme.json
你在主题根目录里写的theme.json，会覆盖掉WordPress的默认配置。
子主题的theme.json（如果存在）
如果你的主题是一个子主题，子主题里的theme.json会覆盖父主题的配置。
用户在站点编辑器里的个性化设置
用户通过“外观 → 编辑器”界面做的任何样式调整，都会保存在数据库里，并且拥有高优先级。也就是说，用户改过的东西，你没法在theme.json里强行覆盖回来——这符合“用户优先”的设计原则。

除了上面这些，开发者还可以通过PHP过滤器（filter hooks）在运行时动态修改theme.json的数据。这对插件开发者来说很实用，但对普通主题开发者来说，先掌握文件配置就足够了。

上手实操：一个实际的主题配置

光说不练假把式，下面给出一个真实可用的theme.json示例。它来自一个简单的博客主题，做的事情包括：

开启外观工具
定义一套简洁的配色方案
设置三种字号
把网站整体背景设为浅灰色，正文用深灰色

json

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"appearanceTools": true,
		"color": {
			"palette": [
				{
					"slug": "base",
					"color": "#f8f9fa",
					"name": "基础白"
				},
				{
					"slug": "contrast",
					"color": "#1e1e1e",
					"name": "正文黑"
				},
				{
					"slug": "primary",
					"color": "#007cba",
					"name": "主色蓝"
				}
			]
		},
		"typography": {
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "小号"
				},
				{
					"slug": "medium",
					"size": "1.25rem",
					"name": "中号"
				},
				{
					"slug": "large",
					"size": "2rem",
					"name": "大号"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "#f8f9fa",
			"text": "#1e1e1e"
		}
	}
}

把这个文件放到你的主题根目录，进入站点编辑器，你会在样式面板里看到刚刚定义的颜色和字号选项。同时，整个网站的背景和文字颜色也会自动应用。

总结

theme.json是WordPress区块主题开发的基石。它用结构化的JSON数据，把主题的全局设置、样式、模板信息集中到了一起。掌握它，你就掌握了控制主题外观和行为的核心手段。

记住几个要点：

settings管功能开关和预设值，styles管实际渲染的样式。
配置有明确的优先级：核心 < 主题 < 子主题 < 用户设置，越往后权重越高。
善用$schema和version字段，能让你在编辑时获得IDE的智能支持。
从简单的配置开始，逐步添加你需要的功能，没必要一开始就写一个庞然大物。

把官方的theme.json参考手册放在手边，遇到具体属性拿不准的时候翻一翻。随着你写的主题越来越多，theme.json会成为你顺手的工具。