VS Code 扩展如何用 vsce 发布到 Marketplace？

发布前先确认这几件事

把 VS Code 扩展发布到 Marketplace，本质上有三件事：扩展本身能正常运行，package.json 信息能被市场识别，发布者账号和访问令牌配置正确。很多发布失败并不是代码问题，而是 README、图标、publisher、PAT 权限这些细节没准备好。

正式发布前，建议先在本地安装一次 .vsix 文件试用。如果本地都装不上，直接 publish 只会把问题推到 Marketplace 的校验阶段。

发布前检查清单

发布前至少检查这些内容：

1. 扩展功能已经跑通过，包括激活事件、命令、配置项和异常场景。
2. README.md 能说明扩展解决什么问题、怎么安装、怎么使用。
3. 图标准备为 128x128 像素的 PNG，路径要和 package.json 中的 icon 一致。
4. package.json 中的 name、displayName、description、publisher、version 都填写正确。
5. 仓库地址、许可证、分类和关键词不要空着。
6. 需要排除的源码、测试文件、截图源文件已写入 .vscodeignore，避免包体过大。
7. 如果扩展包含原生依赖，要确认是否需要按平台发布不同 target。

一个常见判断标准是：别人只看 Marketplace 页面和 README，就能知道这个扩展值不值得安装。

package.json 里哪些字段最容易出错

package.json 是 Marketplace 读取扩展信息的核心文件。下面是一个较完整的示例：

json
{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "A useful VS Code extension",
  "version": "1.0.0",
  "publisher": "your-publisher-name",
  "engines": {
    "vscode": "^1.80.0"
  },
  "categories": ["Other"],
  "keywords": ["utility", "productivity", "vscode-extension"],
  "icon": "icon.png",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-extension"
  },
  "license": "MIT"
}

几个字段要特别留意：

• name：扩展包名，发布后频繁改名会影响识别。
• displayName：展示给用户看的名称，可以比 name 更自然。
• publisher：必须和 Marketplace 发布者名称完全一致，不是 Azure DevOps 组织名随便填一个就行。
• version：每次正式发布都必须递增，否则会被拒绝。
• engines.vscode：表示扩展支持的 VS Code 版本范围，别写得过低，也别为了追新写得太高。
• categories：尽量选择贴近功能的分类，分类乱填会影响用户理解。
• keywords：写用户可能搜索的词，不要堆无关关键词。

如果扩展有命令、配置项或菜单入口，还要确认 contributes 字段里的命令 ID、标题和实际代码一致。命令能注册成功，但标题写得模糊，也会影响用户第一次使用的体验。

如何创建 Marketplace 发布者

发布 VS Code 扩展需要先有发布者，也就是 publisher。通常流程是：

1. 打开 Visual Studio Marketplace 的管理页面：https://marketplace.visualstudio.com/manage
2. 使用 Microsoft 账号登录。
3. 创建一个新的 publisher，填写唯一的发布者名称、显示名称和联系邮箱。
4. 把创建好的 publisher 名称写入扩展的 package.json。

这里最容易混淆的是发布者名称和显示名称。发布者名称是扩展唯一标识的一部分，例如 publisher.extension-name；显示名称只是市场页面上给人看的名字。真正发布时，package.json 里的 publisher 要填发布者名称。

如何创建 Azure DevOps PAT

vsce publish 需要访问令牌，也就是 Azure DevOps 的 Personal Access Token。它不是 Microsoft 账号密码，也不建议使用权限过大的令牌。

创建步骤大致如下：

1. 打开 https://dev.azure.com/ 并登录同一个 Microsoft 账号。
2. 进入用户设置中的 Personal access tokens。
3. 创建新 token。
4. Organization 建议选择可访问的组织范围。
5. Scope 选择 Marketplace 的 Manage 权限。
6. 生成后立刻复制保存，页面关闭后通常无法再次查看明文。

令牌拿到后，不要写进仓库，也不要放到 README、CI 日志或截图里。最稳妥的做法是只在本机 vsce login 时粘贴，CI 发布则放到平台的 Secret 变量中。

安装并登录 vsce

vsce 是发布 VS Code 扩展最常用的命令行工具，现在包名是 @vscode/vsce。

bash
npm install -g @vscode/vsce
vsce --version
vsce login your-publisher-name

命令会要求输入 PAT。登录成功后，本机会保存认证信息。后续执行 vsce publish 时就不必每次重复输入。

如果登录失败，优先检查三点：publisher 名称是否拼错、PAT 是否过期、PAT 是否包含 Marketplace Manage 权限。

先打包成本地 VSIX 文件

不要第一次就直接发布。先打包成本地 .vsix 文件，再安装验证，能省掉很多尴尬。

bash
vsce package
vsce package --out my-extension-1.0.0.vsix

在 VS Code 中可以通过命令面板选择 “Extensions: Install from VSIX...” 安装本地包。重点测试这些内容：

• 扩展是否能被激活。
• 命令是否能执行。
• 配置项是否显示正常。
• README、图标、仓库链接是否正确。
• 打包后是否缺少运行时文件。

如果发现包里混进了测试文件、源码草稿或大体积资源，可以通过 .vscodeignore 排除。例如：

gitignore
.vscode/**
src/**
test/**
*.map
*.vsix
node_modules/.cache/**

注意不要误删运行时需要的编译产物。如果扩展运行依赖 dist，就不能把 dist/** 排除掉。

如何首次发布扩展

确认本地 VSIX 没问题后，可以执行：

bash
vsce publish

这个命令会读取 package.json，打包并上传到 Marketplace。首次发布成功后，市场页面不一定立刻完全可见，搜索索引和统计数据可能有延迟。

如果希望发布时自动递增版本，可以使用：

bash
vsce publish patch
vsce publish minor
vsce publish major
vsce publish 1.1.0

团队协作时要注意把版本变更提交到 Git，否则下一位同事可能基于旧版本继续发布，导致版本号冲突。

预发布版本怎么发

如果新功能还不想推给所有用户，可以发布预发布版本：

bash
vsce publish --pre-release

预发布适合测试较大的功能改动，例如重构语言服务、改动配置格式、引入新 UI。它能让愿意尝鲜的用户提前安装，但不应该拿来替代正常测试。

需要按平台发布时怎么处理

纯 TypeScript 扩展通常不需要区分平台。但如果扩展包含原生依赖、平台二进制文件，或者对不同系统有不同产物，就要考虑 target。

bash
vsce package --target win32-x64
vsce package --target linux-x64
vsce package --target darwin-arm64
vsce publish --target win32-x64

是否需要多平台发布，取决于扩展是否真的包含平台相关文件。不要为了看起来专业而拆平台包，纯 JS 扩展拆了反而增加维护成本。

版本管理应该怎么做

VS Code 扩展一般使用语义化版本：

• major：有不兼容变更，例如配置字段改名、命令行为明显变化。
• minor：增加新功能，但不破坏现有用户使用方式。
• patch：修复 bug、优化文档、处理兼容性小问题。

版本号不是装饰。用户看到频繁的 major 版本，会担心扩展不稳定；长期不更新 patch，又会怀疑项目没人维护。

更新、下架和删除版本

更新扩展的流程很简单：修改代码，更新版本，重新发布。

bash
vsce publish patch

如果确实需要下架扩展，可以使用 unpublish。实际命令通常需要带上发布者和扩展名，格式类似：

bash
vsce unpublish your-publisher-name.my-extension

下架是高风险操作。已经安装的用户、文档链接、依赖说明都会受到影响。除非扩展有严重安全问题、侵权问题或完全废弃，不建议轻易下架。

Marketplace 页面怎么写更容易被安装

用户通常会先看三样东西：扩展能解决什么问题、怎么用、是否可信。

• 描述开头直接说用途：不要用“一个强大的插件”这类空话。
• README 放最短可用路径：安装后第一步点哪里、执行什么命令、预期看到什么结果。
• 截图只放必要内容：截图要能解释功能，不要放大段无关 UI。
• 关键词贴近搜索意图：例如 formatter、snippet、theme、debugger、productivity。
• 仓库和许可证清楚：开发者工具类扩展尤其需要可信度。

常见发布失败原因

publisher 不匹配

package.json 里的 publisher 和 Marketplace 创建的 publisher 不一致，会导致发布失败。大小写、短横线、拼写都要对齐。

PAT 权限不够

只创建了普通 Azure DevOps token，但没有 Marketplace Manage 权限，vsce login 或 vsce publish 会失败。重新生成 PAT 比反复改命令更快。

version 没有递增

同一个版本不能重复发布。修复一个错别字也要递增 patch 版本。

.vscodeignore 排除了运行文件

为了减小体积把 dist、out 或资源文件排除了，结果本地源码能跑，安装 VSIX 后不能跑。发布前安装本地包就是为了抓这类问题。

包体里包含敏感信息

不要把 .env、测试 token、私钥、内部接口文档打进扩展包。发布前可以解压 .vsix 看一眼内容，尤其是公司项目转开源时更要小心。

一个更稳妥的发布流程

实际项目里可以按这个顺序走：

1. 本地跑测试和 lint。
2. 检查 package.json、README、LICENSE、icon。
3. 更新 changelog 和版本号。
4. 执行 vsce package。
5. 在 VS Code 里安装生成的 VSIX。
6. 用真实场景试一遍核心功能。
7. 确认 .vsix 中没有敏感文件和无关大文件。
8. 执行 vsce publish。
9. 打开 Marketplace 页面检查展示效果。

发布 VS Code 扩展不难，难的是把账号、令牌、版本、包内容这些细节处理稳定。流程固定下来后，每次发布只需要关注两个问题：这次改动是否值得发一个新版本，以及用户安装后能不能马上用起来。