VSCode自定义主题需同时配置colors（UI控件色）和tokenColors（语法高亮）两个顶层字段，缺一不可；colors用预定义color ID，tokenColors用TextMate scope并支持透明度；通过Developer: Inspect Editor Tokens and Scopes精准获取scope；package.json中uiTheme只能设为vs-dark或vs。
VSCode 自定义主题不是改改 workbench.colorCustomizations 就能搞定的——它分两层：一层是 UI 控件色（侧边栏、标题栏、按钮等），另一层是代码语法高亮（textMateRules）。只动其中一层，主题会看起来“怪怪的”，比如背景对了但括号颜色还是默认蓝。
theme 文件必须包含 tokenColors 和 colors 两个顶层字段
很多人新建 .json 主题文件后只填 colors，结果语法高亮完全没变。VSCode 的主题系统强制要求同时提供：colors 控制 UI 元素（如 editor.background、activityBar.foreground），tokenColors 控制代码着色（如 comment、keyword、string）。缺一不可，否则 VSCode 会静默忽略整个主题。
实操建议：
-
colors字段值是纯对象，键名必须是 VSCode 预定义的 color ID（如editorLineNumber.foreground），不能自创；查完整列表请打开命令面板 →Developer: Generate Color Theme From Current Settings -
tokenColors是数组，每项含name（仅注释用）、scope（TextMate 作用域，如support.function.builtin）、settings（含foreground、background、fontStyle） - 别直接写十六进制色值，用
#RRGGBBAA格式（带 alpha），否则透明度失效；fontStyle只接受"italic"、"bold"、"underline"或空字符串，不支持组合写法如"bold italic"
如何精准定位某个语法元素的 TextMate scope
想改函数名颜色，但不知道该配哪个 scope？靠猜或搜文档效率极低。正确做法是用 VSCode 内置诊断工具：
把光标停在目标代码上（比如一个 console.log() 中的 log），按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P），输入并运行 Developer: Inspect Editor Tokens and Scopes。面板里会显示当前 token 的完整 scope 链（如 support.function.console.js），优先用最具体的那一项。
注意点：
- 不同语言插件注册的 scope 不同，JavaScript 的
function和 Python 的functionscope 完全不一样；不要跨语言复用 scope - scope 匹配是“从左到右最长前缀匹配”，所以
support.function会覆盖更宽泛的support，但不会影响entity.name.function - 如果 Inspect 工具显示多个 scope，选顶部第一个（最精确），避免误配全局规则
package.json 里声明 theme 时 uiTheme 必须设为 vs-dark 或 vs
即使你做的主题是浅色系，package.json 中的 contributes.themes.uiTheme 字段也不能写 vs-light 或留空。VSCode 目前只认两个合法值：vs-dark（深色 UI）、vs（浅色 UI）。填错会导致主题安装后无法启用，控制台报错 Invalid uiTheme value in theme contribution。
这个字段只决定主题启用时 VSCode 是否自动切换 UI 模式（比如标题栏、侧边栏底色），不影响你实际在 colors 里写的值。也就是说：你可以用 uiTheme: "vs-dark"，但把 editor.background 设成 "#ffffff"，UI 仍是深色模式框架，编辑器区域却白得刺眼——这是允许的，也是常见做法。
其他关键配置项：
-
path必须指向你的.json主题文件，路径相对于package.json所在目录，例如"./themes/my-theme-color-theme.json" -
label是用户在「颜色主题」列表里看到的名字，别含空格或特殊字符，否则某些旧版 VSCode 会加载失败 - 发布前务必删掉
package.json中的preview字段（如有），它已废弃且会阻止主题被识别
真正难的不是写 JSON，而是保持 colors 和 tokenColors 的视觉一致性——比如注释灰度要和侧边栏 inactive 状态的灰度协调，字符串颜色要在多种背景（浅/深/高对比度）下都可读。多数人卡在这一步，反复调色却总觉得“差点意思”，其实是因为没先定好基础色板，而是东一处西一处地修。
