WordPress主题JSON全解：theme.json的每一层配置

theme.json是块主题（Block Theme）的核心配置文件，但大多数主题开发者只用到了它30%的能力。这篇文章带你逐层拆解theme.json的完整配置体系，包括一些官方文档没有强调但实际开发中必用的设置。

Settings层：定义设计系统的原子变量

Settings层控制”编辑器中可用的选项”：调色板、字体大小、间距预设、自定义CSS属性。关键技巧：settings.custom可以定义任意CSS变量并通过var(--wp--custom--xxx)在全局使用，这让你可以在theme.json中集中管理设计令牌而非散落在一堆CSS文件中。settings.spacing.spacingScale配合clamp()可以实现流体间距——屏幕越宽间距越大，一个设置解决响应式。

Styles层：默认外观与块样式

Styles层定义实际渲染的外观：颜色、排版、布局。最常见的误区是styles.blocks中重复定义已在全局样式声明过的属性。正确的做法是全局定义90%的样式，blocks层只写差异。另外 styles.elements（button、heading、link等）可以统一控制跨块的元素外观，比在CSS中逐个覆盖高效得多。

templateParts与customTemplates

这两个配置定义了主题暴露给站点编辑器的模板区域和自定义模板。如果你没有在theme.json中声明customTemplates，用户在站点编辑器中就看不到你精心制作的page-about.php模板。务必为每个自定义模板提供title和postTypes——后者限制模板只在特定post type中可选，避免用户误用。

版本管理

"version": 2和"version": 3之间存在不小的差异。v3支持了appearanceTools的更多细分控制、useRootPaddingAwareAlignments的智能对齐，以及shadow预设。如果你的WP版本≥6.5，强烈建议升级到v3并充分利用这些新特性。