必须声明 contributes.themes，因为 VSCode 仅通过该字段识别主题插件；漏写或 uiTheme 填错（如用 "dark" 代替 "vs-dark"）会导致主题静默失效、不显示在颜色主题列表中。
主题元数据文件（package.json）不是可选配置，而是 VSCode 主题插件能被识别、加载和发布的强制入口；漏掉 contributes.themes 或写错 uiTheme 值，插件安装后根本不会出现在「颜色主题」列表里。
为什么 package.json 里必须声明 contributes.themes
VSCode 不靠文件名或目录结构发现主题，只扫描已安装扩展的 package.json 中 contributes.themes 字段。这个字段告诉 VSCode：“我这个扩展提供一个或多个主题，它们的定义文件在哪儿”。没有它，哪怕 themes/my-theme.json 写得再规范，VSCode 也当普通 JSON 文件忽略。
-
contributes.themes必须是数组，每项含label（用户看到的主题名）、uiTheme（只能是"vs-dark"或"vs"，不能填"dark"或"light"）、path（相对于插件根目录的 JSON 路径，如"themes/dark-sage.json"） -
uiTheme填错是最常见失败原因：VSCode 1.80+ 已废弃"dark"/"light"值，只认"vs-dark"（对应暗色 UI）和"vs"（对应亮色 UI）；填错会导致主题灰色不可选 - 如果主题同时支持暗/亮模式，必须声明两个独立 theme 条目，分别指定
uiTheme: "vs-dark"和uiTheme: "vs"，不能在一个条目里混用
theme JSON 文件路径和命名的硬性约束
VSCode 加载主题时对路径和文件名大小写、字符极其敏感，任何偏差都会静默失败——你不会收到报错，只是主题不出现。
- 路径必须是
./themes/xxx.json，且themes/目录必须手动创建在插件根目录下；VSCode 不会自动建，也不认src/themes/、dist/themes/或.vscode/themes/ - 文件名只能含小写字母、数字、连字符（
-），禁止空格、下划线、大写字母、中文；例如my-cool-theme.json合法，MyCoolTheme.json或my_cool_theme.json会加载失败 -
path字段里的值必须和实际文件路径完全一致（包括大小写），比如文件叫dark-sage.json，但path写成"themes/Dark-Sage.json"，主题就消失
发布前必须校验的三个关键字段
打包发布前，package.json 里这三项缺失或错误，会导致插件在 Marketplace 审核失败，或用户安装后无法启用主题。
-
publisher：必须是你在 Visual Studio Marketplace 注册的 publisher ID，不是用户名或邮箱；ID 错误会导致vsce publish报Unauthorized -
activationEvents：主题插件必须声明["onStartup"]或["onLanguage:json"]等合理激活事件；空数组或缺失该字段会让 VSCode 认为插件“无需激活”，从而跳过加载 -
engines.vscode：建议设为=1.80.0"或更高；设太低（如"^1.50.0"）可能因旧版兼容问题被 Marketplace 拒绝，设太高（如"^1.99.0"）则新用户无法安装
如何验证 package.json 是否生效
别等发布后再排查——本地就能快速验证 package.json 配置是否被正确读取。
- 按
F5启动 Extension Development Host，在新窗口里打开命令面板（Ctrl+Shift+P），运行Preferences: Color Theme；你的主题名应出现在列表顶部，带插件图标前缀（如[my-publisher]） - 如果没出现，打开开发者工具（
Ctrl+Shift+I），切到 Console 标签页，搜theme或contributes，常能看到类似Ignoring contribution 'themes' from extension 'my-publisher.my-theme' because of invalid uiTheme value的提示 - 检查插件输出面板（
View → Output，下拉选Extension Host），启动时会打印所有成功注册的主题路径；没打印你的路径，说明contributes.themes根本没被解析
最易被忽略的是 uiTheme 的取值限制和 themes/ 目录的手动创建——这两点出错，整个主题就卡在“看不见”的状态，连调试入口都没有。
