必须将主题文件置于./themes/midnight-sage.json路径，package.json中contributes.themes[].uiTheme严格设为vs-dark或vs，并在theme文件中同时定义colors（用官方color ID）和tokenColors（含正确TextMate scope）两个字段。
主题文件必须放在 ./themes/ 目录下，名字全小写+连字符+.json
VSCode 不会扫描任意位置的 JSON 文件——它只认固定路径。你得手动在插件根目录下建一个 themes 文件夹（不能叫 theme、Themes，也不能嵌套在 src/ 里），然后把主题文件放进去，例如：midnight-sage.json。
常见失败路径：
-
themes/MidnightSage.json→ 首字母大写，不识别 -
themes/midnight sage.json→ 含空格，解析失败 -
my-theme.json（直接放根目录）→ VSCode 根本看不到 -
src/themes/my-theme.json→ 路径嵌套过深，无效
唯一有效的完整路径是：./themes/midnight-sage.json（注意是项目根目录下的 themes/）。
package.json 中 contributes.themes[].uiTheme 只能填 vs-dark 或 vs
这个字段不是描述“你想要什么风格”，而是强制告诉 VSCode：“请用深色 UI 框架加载我”或“请用浅色 UI 框架加载我”。填错就静默失效，主题不会出现在「颜色主题」列表里。
合法值只有三个：
-
"uiTheme": "vs-dark"→ 对应深色 UI（比如状态栏、侧边栏用暗色系） -
"uiTheme": "vs"→ 对应浅色 UI（不能写vs-light或light） -
"uiTheme": "hc-black"→ 高对比度黑底（极少数场景用）
哪怕你 colors 里全配了浅色值，只要 uiTheme 是 vs-dark，VSCode 就按深色模式渲染所有 UI 组件；反之亦然。
没配 tokenColors，语法高亮永远是默认色
只改 editor.background 和 sideBar.background，打开代码一看：注释还是灰色、function 还是蓝色——这不是主题没生效，是你漏了 tokenColors。
tokenColors 是数组，每项必须含两个关键字段：
-
scope：TextMate 作用域名，别靠猜。把光标停在目标词上（比如一个return），按Cmd+Shift+P→Developer: Inspect Editor Tokens and Scopes，取顶部第一个 scope（如keyword） -
settings：对象，至少含foreground（支持#rrggbb、rgb()、命名色，甚至带透明度如#00000080）
最小可用示例：
"tokenColors": [
{ "scope": "comment", "settings": { "foreground": "#718096" } },
{ "scope": "keyword", "settings": { "foreground": "#e53e3e" } },
{ "scope": "string", "settings": { "foreground": "#48bb78" } }
]
colors 和 tokenColors 缺一不可
这是最常被跳过的硬性条件。VSCode 主题验证逻辑是：同时存在 colors（UI 元素）和 tokenColors（语法着色）才视为有效主题。只写一个，插件安装后主题列表里照样不显示。
colors 里推荐先配这几个关键项：
-
"editor.background"：编辑器主背景，决定整体明暗基调 -
"editor.foreground"：默认文字色，影响未被tokenColors覆盖的文本 -
"activityBar.background"：左侧活动栏背景，UI 层级感起点 -
"tab.activeBackground"：当前标签页背景，直接影响焦点感知
真正容易被忽略的是：你改了 settings.json 里的 workbench.colorCustomizations，那只是用户级临时覆盖，不算“创建主题”——它无法导出、不能分享、也不进主题列表。要发布、复用、调试，必须走 themes/*.json + package.json 注册这条路。
