WordPress如何正确使用theme.json覆盖功能切换自定义调色板

styles/目录下的明暗配色文件不会被WordPress自动扫描加载，必须在根目录theme.json中显式注册全局样式变体，Gutenberg编辑器才会在全局样式面板中展示对应的切换选项，加载对应调色板配置。

• 校验文件结构
  先确认主题目录结构符合规范，层级如下：

  主题根目录/
  ├─ theme.json （根配置文件，version固定为2）
  └─ styles/ （目录名必须全小写，不能为其他拼写）
     ├─ light.json
     └─ dark.json
  

  两个变体json不需要写和根theme.json完全一致的全量结构，仅保留需要覆盖的配置项即可，冗余配置不会报错但会增加不必要的加载体积。
• 在根theme.json中注册样式变体
  打开根目录theme.json，在顶层新增数组类型的styles字段（注意不要和配置默认全局样式的对象类型style字段混淆，二者字段名差一个s，类型错误会导致变体完全不加载），注册两个配色变体，示例配置如下：

  {
    "version": 2,
    "settings": {
      "appearanceTools": true,
      "color": {
        "custom": false,
        "defaultPalette": false,
        "palette": [
          // 此处保留你原有的基础默认调色板配置
        ]
      }
    },
    "styles": [
      {
        "title": "亮色模式",
        "slug": "light",
        "path": "styles/light.json"
      },
      {
        "title": "暗色模式",
        "slug": "dark",
        "path": "styles/dark.json"
      }
    ]
  }
  

  每个变体的三个必填参数说明：
  • title：编辑器样式切换面板对外展示的变体名称，支持中文
  • slug：变体的唯一标识，必须和对应json的文件名（不含.json后缀）完全一致
  • path：变体文件相对于主题根目录的相对路径，必须填写准确
• 调整变体json的配置结构
  打开light.json、dark.json，确保文件为合法JSON格式，不需要声明version字段，仅保留要覆盖的调色板配置即可，示例：

  {
    "settings": {
      "color": {
        "palette": [
          // 此处填写对应明暗模式下的自定义调色板色值
        ]
      }
    }
  }
  

• 清除缓存验证效果
  配置完成后清空站点缓存、浏览器缓存，进入Gutenberg编辑器点击右上角的全局样式按钮（半黑半白圆形图标），在「浏览样式」区域就能看到注册好的亮色、暗色两个选项，点击切换即可加载对应配置的自定义调色板。

• 不要混淆style和styles两个顶层字段：style是对象类型，用于配置主题默认全局样式；styles是数组类型，用于注册所有可选样式变体，写错字段类型会导致变体完全不识别
• 变体json中不要加version字段，否则会出现配置合并冲突，导致调色板覆盖失效
• 如果需要前台实现明暗模式自动跟随系统切换，需要额外搭配前端脚本读取用户选中的变体标识，给html标签添加对应属性并适配CSS变量，编辑器端无需额外配置即可正常切换调色板

内容的提问来源于stack exchange，提问作者JalalJaberi