VSCode主题插件开发本质是精准配置JSON：package.json需声明contributes.themes，含label、uiTheme、path；color-theme.json的tokenColors依赖正确scope和合法颜色格式；light/dark/hc主题必须分文件；发布前须验证JSON格式、路径及scope兼容性。
VSCode 主题插件开发不是写代码，而是精准配置 JSON —— 出问题基本就是 package.json 路径错、tokenColors 里 scope 写错、颜色格式非法，或者 light/dark 混在同一个文件里。
主题插件的 package.json 必须声明 contributes.themes
VSCode 不会自动识别你的主题，必须显式告诉它“我提供了一个 color theme”。关键字段是 contributes.themes 数组，每项需包含：
-
label：用户在「颜色主题」列表里看到的名字（如"My Dark Theme"） -
uiTheme：指定类型，只能是"vs-dark"（暗色）、"vs"（亮色）或"hc-black"（高对比度） -
path：指向你主题 JSON 文件的**相对路径**，且该文件必须在插件根目录下可直接访问（不能放在src/或dist/里）
常见错误：path 写成 "./themes/dark.json" 但实际文件在 themes/dark.json —— VSCode 不解析 . 和 ..，只认根目录起始的路径，应写 "themes/dark.json"。
color-theme.json 的 tokenColors 是语法高亮核心
这个数组控制所有代码着色，每一项是一个对象，必须含 scope 和 settings：
-
scope是关键：它不是类名，而是 TextMate 语法规则链，比如"entity.name.function.ts"或"string.quoted.double.js"。靠猜几乎必失败 - 验证 scope 的唯一可靠方式：打开对应语言文件 →
Ctrl+Shift+P→ 输入Developer: Inspect Editor Tokens and Scopes→ 鼠标悬停目标文本，看面板显示的完整 scope 链 -
settings.foreground必须是合法十六进制，如"#ff6b6b"；"ff6b6b"或"rgb(255,107,107)"均无效 -
settings.fontStyle只接受"italic"、"bold"、"underline"或空字符串""；多个样式要用空格分隔，如"bold italic"，不能写成"bold,italic"
light / dark / hc 主题必须拆成独立 JSON 文件
VSCode 强制要求不同 UI 类型的主题分离。你不能在一个 theme.json 里用条件判断切换颜色 —— 它不执行 JS，也不支持变量或逻辑。
- 每个主题类型（
vs-dark、vs、hc-black）必须对应package.json中contributes.themes的一项，并指向不同文件 - 例如：暗色主题用
themes/my-dark.json，亮色用themes/my-light.json，两者结构一致但colors和tokenColors值不同 - 如果只提供一个主题却在
package.json里声明了三种uiTheme，用户切换时会 fallback 到默认主题，且无报错提示
发布前必须手动验证 color-theme.json 格式与路径
VSCode 不校验主题 JSON 的语义正确性，只做基础 JSON 解析。很多“主题不生效”问题其实发生在安装前：
- 用 VSCode 打开你的
color-theme.json，看右下角是否显示JSON with Comments—— 如果显示JSON，说明有注释（VSCode 主题 JSON 不允许任何注释） - 检查所有
foreground值是否以#开头且长度为 7 或 4（如#fff）；background同理 - 确认
package.json中声明的path文件真实存在，且大小写完全匹配（Windows 上常因大小写不敏感掩盖问题，Linux/macOS 会直接失败） - 本地测试：把插件文件夹拖进 VSCode 的扩展视图 → 点「启用」→
Ctrl+K Ctrl+T查看是否出现在主题列表中
最易被忽略的是 scope 的层级优先级和语言扩展依赖：TypeScript 的 entity.name.function.ts 在没装 TypeScript 插件的机器上会退化成 entity.name.function，甚至只剩 entity.name —— 所以建议在 tokenColors 里同时写具体和泛化的 scope，并把更具体的规则放在前面。
