// Created At 2026-02-25

创建并发布你的第一个VS Code主题：从零到上手指南

如果你已经有一定的编程基础（熟悉 JavaScript、JSON、命令行），但对如何将自己的配色方案变成 VS Code 主题一无所知，这篇文章正是为你准备的。

去年年末我为个人博客设计了一套名为 Moongate 的配色，极简科幻风格。最近突发奇想：能不能把它变成 VS Code 主题？经过几天摸索，终于成功发布。下面我把整个流程拆解成清晰的步骤，希望能帮你少踩坑。

一、准备工作

确保你已安装：

Node.js（含 npm）
Git（可选，但推荐）

然后全局安装 Yeoman 和 VS Code 扩展生成器：

npm install -g yo generator-code

二、生成主题项目

yo code

按提示选择：

New Color Theme
No, start fresh（不导入现有主题）
填写信息：
- Extension name：你的主题名（如 moongate-theme）
- Description：简短介绍，如 🌙 Where Moon Meets Code - 极简科幻终端主题
- Publisher name：你的发布者ID（需提前在 VS Code 市场注册，见后文）
选择基础主题：Dark 或 Light
主题显示名称：如 Moongate Dark

生成器会创建项目文件夹，结构如下：

your-theme/
├── themes/
│   └── your-theme-color-theme.json
├── package.json
├── README.md
├── CHANGELOG.md
└── ...

三、核心概念：`colors` 与 `tokenColors`

主题配置文件位于 themes/ 下，主要包含两部分：

colors：定义编辑器 UI 的颜色（标题栏、状态栏、侧边栏等）
tokenColors：定义代码语法高亮（关键字、字符串、注释等）

🔍 如何找到正确的颜色键名？

VS Code 提供了两个超实用工具：

界面颜色：按下 Ctrl+Shift+P，运行 Developer: Generate Color Theme From Current Settings。它会生成当前主题所用所有颜色键名的 JSON，你可以直接复制需要的键名（如 editor.background）。
语法作用域（scope）：打开一个代码文件，把光标放在你想着色的元素上，运行 Developer: Inspect Editor Tokens and Scopes。弹出的窗口会显示该元素的 textmate scopes 列表，选择最具体的那一个用于 tokenColors 规则。

🎨 配置示例

"colors": {
  "editor.background": "#0f172a",
  "editor.foreground": "#e2e8f0",
  "statusBar.background": "#0f172a",
  // ... 更多 UI 键名
},
"tokenColors": [
  {
    "name": "Comment",
    "scope": ["comment", "punctuation.definition.comment"],
    "settings": {
      "fontStyle": "italic",
      "foreground": "#94a3b8"
    }
  },
  {
    "name": "Keyword",
    "scope": ["keyword", "storage.type", "storage.modifier"],
    "settings": {
      "foreground": "#3b82f6",
      "fontStyle": "bold"
    }
  }
  // ... 其他规则
]

注意：tokenColors 数组顺序很重要，后面的规则会覆盖前面相同 scope 的规则。

四、本地调试

在 VS Code 中打开项目文件夹。
按 F5 启动“扩展开发主机”窗口。
在新窗口中按 Ctrl+K Ctrl+T，选择你的主题。
打开测试代码文件，实时查看效果。
修改主题 JSON 后，在开发主机中按 Ctrl+R 重新加载，修改立即生效。

五、完善细节

状态栏、标题栏：别忘了配置这些区域，键名参考生成的 JSON。
对比度：可用工具检查文字对比度是否达标（WCAG 要求 ≥4.5:1）。
语义高亮：如果希望更精细的着色，可以启用 VS Code 的语义高亮，并在主题中添加 semanticTokenColors 配置（进阶，可暂时忽略）。

六、准备发布

1. 完善 `package.json`

关键字段：

{
  "name": "your-theme-name",
  "displayName": "Your Theme Display Name",
  "description": "简短描述",
  "version": "1.0.0",
  "publisher": "你的发布者ID",
  "engines": { "vscode": "^1.109.0" },
  "categories": ["Themes"],
  "icon": "images/icon.png", // 128x128 PNG 图标，路径要正确
  "repository": {
    // 可选，但推荐
    "type": "git",
    "url": "https://github.com/yourname/your-theme"
  }
}

2. 准备截图

在根目录创建 images 文件夹，放入至少 3-5 张不同语言的代码截图（建议 1280×640），用于 README。

3. 编写 README.md

包含主题名称、预览截图、设计理念、安装方法、配色表（可选）等。

4. 添加 LICENSE

建议使用 MIT 许可证，创建 LICENSE 文件。

5. 创建 `.vscodeignore`

排除不需要打包的文件，例如：

.vscode/**
.gitignore
node_modules

注意：不要排除 images/ 文件夹，否则截图会丢失。

七、打包与发布

1. 安装发布工具

npm install -g @vscode/vsce

2. 打包测试

vsce package

如果成功，会生成 .vsix 文件。可以拖进 VS Code 手动安装测试。若失败，仔细阅读错误提示，常见原因是 icon 路径错误或 .vscodeignore 误排除了必要文件。

3. 获取 Personal Access Token

登录 Azure DevOps（用你注册市场的微软账号）。
右上角头像 → Personal access tokens → New Token。
名称随意，组织选 All accessible organizations，有效期建议 1 年。
权限：只勾选 Marketplace → Manage。
创建后立即复制 Token（只显示一次）。

4. 登录并发布

vsce login 你的发布者ID
# 粘贴刚才的 Token（不会显示，直接回车）

vsce publish

几秒后主题就会上传。约 5-10 分钟即可在 VS Code 中搜索到。

常见发布错误：

Token verification failed：权限未正确设置或 Token 过期，重新生成。
Version already exists：版本号重复，更新 package.json 中的 version。
网络问题：尝试更换网络或使用代理。

八、发布后

查看市场页面：https://marketplace.visualstudio.com/items?itemName=你的发布者ID.你的主题名
登录市场管理后台查看报表（页面浏览、安装量、转化率）。
在 GitHub 仓库添加 README 徽章（如版本、下载量）。
收集反馈，准备后续更新。

九、最后

从自己的配色到可分享的 VS Code 主题，整个过程并不复杂，核心就是理解 colors 和 tokenColors 的结构，并善用 VS Code 自带的开发者工具。遇到问题时，多看错误提示，多查官方文档。

如果你也做出了自己的主题，欢迎分享。代码世界那么大，总有人和你喜欢同一片月光。

十、一点建议：善用 AI，让创作更高效

作为一名独立开发者，你可能会发现，从配色方案到语法规则，有太多细节需要打磨。这时候，AI 可以成为你最得力的助手。无论是生成初始的 tokenColors 模板、帮你调试某个 scope 的匹配问题，还是撰写文档、翻译 README，AI 都能在几秒钟内给出方案，节省你大量时间。

在我开发 Moongate Dark 的过程中，AI 帮我梳理了颜色变量、优化了视觉远近法，甚至在我卡在某个配置时提供了多种思路。它就像一位永不疲倦的伙伴，随时待命。

但请记住：AI 是工具，不是决策者。最终的审美判断、设计哲学，还是要由你自己来定。你可以用 AI 快速试错、快速产出，但不要让它替你决定“什么好看”。你的独特性，正是 AI 无法替代的部分。

如果你还没有尝试过在编程中使用 AI，不妨从现在开始。它不会让你失业，反而会让你从繁琐的细节中解放出来，把精力集中在真正重要的事情上——创造属于你自己的作品。