主题打包与发布

主题开发完成后，打包、测试、发布、运营决定了它能否被社区使用。本文走完整条发布链路。

用 yo code 生成主题项目

yo code 提供主题向导，自动生成项目骨架：

$ npx yo code

? What type of extension do you want to create? New Color Theme
? Import an existing TextMate theme (.tmTheme)? No
? What is the name of your extension? my-ocean-theme
? What is the display name of your extension? My Ocean Theme
? What is the identifier? my-ocean-theme
? What's your publisher name? mypublisher
? What kind of theme? Dark

向导生成的项目结构：

my-ocean-theme/
 ├── themes/
 │    └── my-ocean-theme-color-theme.json
 ├── .vscode/launch.json
 ├── package.json
 └── README.md

launch.json 已配置好 F5 启动"扩展开发宿主"，可以直接调试主题。

主题预览与测试

扩展开发宿主

按 F5 打开开发宿主窗口，在主题选择器中选择你的主题实时预览。改动主题 JSON 后：

Ctrl+Shift+P → Developer: Reload Window

重载后应用最新改动。

测试清单

检查项	方法
语法高亮	打开多种语言文件检查 tokenColors
语义着色	打开 TS 文件检查 semanticTokenColors
UI 颜色	浏览侧边栏/状态栏/菜单/对话框
高对比度	切换到高对比主题检查可读性
终端	打开终端检查 ANSI 颜色
差异编辑器	对比文件检查 diff 颜色

自动测试（可选）

用脚本验证主题文件是合法 JSON：

node -e "JSON.parse(require('fs').readFileSync('./themes/theme.json','utf8')); console.log('OK')"

准备发布元数据

发布前完善 package.json：

{
  "name": "my-ocean-theme",
  "displayName": "My Ocean Theme",
  "description": "深海蓝配色主题，支持暗色与亮色",
  "version": "1.0.0",
  "publisher": "mypublisher",
  "engines": { "vscode": "^1.80.0" },
  "categories": ["Themes"],
  "keywords": ["theme", "dark", "ocean", "blue"],
  "galleryBanner": {
    "color": "#0d1117",
    "theme": "dark"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/your/repo"
  },
  "license": "MIT",
  "contributes": {
    "themes": [
      {
        "label": "My Ocean Dark",
        "uiTheme": "vs-dark",
        "path": "./themes/my-ocean-dark.json"
      }
    ]
  }
}

字段	发布必备
publisher	必须，Marketplace 发布者 ID
engines.vscode	必须，兼容的最低版本
categories	建议，主题类 Themes
galleryBanner	建议，市场横幅配色

打包扩展

使用 vsce（Visual Studio Code Extension 工具）：

# 安装打包工具
npm install -g @vscode/vsce

# 打包为 .vsix
vsce package

# 指定版本打包
vsce package 1.0.1

打包输出

DONE  Packaged: my-ocean-theme-1.0.0.vsix (1.2 MB)

.vsix 是扩展的安装包格式，可直接分发安装：

VS Code 扩展面板 → ... → Install from VSIX...

打包前检查

vsce ls      # 列出将打包的文件
vsce ls --tree

vsce package 会自动：

• 校验 package.json 必需字段
• 生成 CHANGELOG.md（若有 CHANGELOG.md）
• 检查 README 与 license

发布到 Marketplace

创建发布者

1. 访问 marketplace.visualstudio.com 登录
2. 创建 Publisher（发布者），获得唯一 ID
3. 生成 Personal Access Token（PAT）

创建 Azure DevOps 组织与 PAT

1. https://dev.azure.com 创建组织
2. 用户设置 → Personal Access Tokens → 新建
3. 权限选择 Marketplace → Manage
4. 复制 Token

发布命令

# 登录（只需一次，Token 会保存）
vsce login mypublisher

# 发布（版本号自动递增或手动指定）
vsce publish

# 指定版本发布
vsce publish 1.0.1

发布成功后，扩展在市场搜索可见：

DONE  Published my-ocean-theme@1.0.1
INFO  Open https://marketplace.visualstudio.com/items?itemName=mypublisher.my-ocean-theme

更新主题

# 增加版本号并发布
vsce publish patch    # 1.0.0 → 1.0.1
vsce publish minor    # 1.0.0 → 1.1.0
vsce publish major    # 1.0.0 → 2.0.0

主题兼容性

VS Code 版本

主题中使用了高版本特性（如 hc-light）需提高 engines.vscode：

{
  "engines": { "vscode": "^1.82.0" }
}

旧版本 VS Code 无法安装 engines 不满足的扩展。

与其他扩展的冲突

冲突类型	处理
颜色键名相同	后激活的扩展覆盖，主题作者无法控制
语义 token 类型冲突	用 semanticTokenColors 覆盖
与其他主题同名 label	用户自行选择

主题之间天然不冲突（用户同时只启用一个），但要注意不与用户自定义颜色设置冲突——那是用户的选择。

下载量与评价运营

README 是门面

Marketplace 页面展示 README，直接影响转化率：

# My Ocean Theme

深海蓝配色主题，专为长时间编码设计。

## 特性

- 暗色与亮色双版本
- 低蓝光护眼配色
- 完整语义着色支持

## 截图

![Dark](/images/dark.png)
![Light](/images/light.png)

运营建议

手段	说明
高质量截图	首屏印象，放代码高亮效果
版本更新记录	每次更新写清变更
响应 issue	收集真实用户环境反馈
多语言 README	面向国际社区
徽章展示	下载量/评分/许可证徽章

统计查看

Marketplace 扩展页显示安装量、评分与下载趋势。VS Code 内也可通过 vsce 查看：

vsce show mypublisher.my-ocean-theme

发布常见问题

问题	解决
publisher 不存在	先在 Marketplace 创建发布者
PAT 无效	重新生成并确认权限为 Marketplace/Manage
版本已存在	递增版本号后重试
打包包含多余文件	配置 .vscodeignore 排除
README 缺失	创建 README.md 后再发布

.vscodeignore 排除无关文件

.vscode/**
src/**
node_modules/**
**/*.map
**/*.ts
.gitignore

主题发布链路闭环：yo code 生成 → 开发宿主预览 → vsce package 打包 → vsce publish 发布 → 市场运营。下一篇实战开发三套主题。