发布扩展

当你制作出一个高质量的扩展后，可以将其发布到 VS Code 扩展市场，以便他人查找、下载和使用。或者，你也可以将扩展打包为可安装的 VSIX 格式并分享给其他用户。

本主题涵盖

• 使用 vsce（用于管理 VS Code 扩展的 CLI 工具）
• 打包、发布和取消发布扩展
• 注册发布者（发布扩展所必需）

vsce

vsce 是 "Visual Studio Code Extensions" 的缩写，是一个用于打包、发布和管理 VS Code 扩展的命令行工具。

安装

确保已安装 Node.js，然后运行

npm install -g @vscode/vsce

使用方法

你可以使用 vsce 轻松地打包和发布你的扩展。

$ cd myExtension
$ vsce package
# myExtension.vsix generated
$ vsce publish
# <publisher id>.myExtension published to VS Code Marketplace

vsce 还可以搜索、获取元数据以及取消发布扩展。有关所有可用 vsce 命令的参考，请运行 vsce --help。

发布扩展

发布工具会检查以下限制

• package.json 中提供的图标不得为 SVG 格式。
• package.json 中提供的徽章（badge）不得为 SVG 格式，除非它们来自受信任的徽章提供商。
• README.md 和 CHANGELOG.md 中的图像 URL 必须解析为 https URL。
• README.md 和 CHANGELOG.md 中的图像不得为 SVG 格式，除非它们来自受信任的徽章提供商。

Visual Studio Code 使用 Azure DevOps 来提供市场服务。这意味着扩展的身份验证、托管和管理均通过 Azure DevOps 提供。

vsce 只能使用个人访问令牌 (Personal Access Tokens) 来发布扩展。你需要至少创建一个才能发布扩展。

获取个人访问令牌

你可以通过 Azure DevOps 门户创建个人访问令牌。创建步骤如下

1. 如果你还没有 Azure DevOps 组织，请按照创建组织文章中的步骤操作。

2. 前往 Azure DevOps 门户并选择你的组织。

3. 打开个人资料图片旁边的“用户设置”下拉菜单，选择 Personal access tokens（个人访问令牌）

   

4. 在 Personal Access Tokens 页面上，选择 New Token（新令牌）

   

5. 在创建新个人访问令牌的模态窗口中，为令牌选择以下详细信息

   • 名称：为令牌指定任意名称
   • 组织：All accessible organizations（所有可访问的组织）
   • 过期时间（可选）：设置令牌所需的过期日期
   • 范围：Custom defined（自定义定义）
     • 点击 Scopes 部分下方的 Show all scopes 链接
     • 在 Scopes 列表中，滚动到 Marketplace 并选择 Manage 范围

   

6. 点击 Create（创建）。

   你将看到刚刚创建的个人访问令牌。复制并将其保存在安全的地方，你需要它来创建发布者。

创建发布者

发布者是一个能够将扩展发布到 Visual Studio Code 市场的身份。每个扩展都需要在其 package.json 文件中包含一个 publisher 标识符。

创建发布者步骤

1. 前往 Visual Studio 市场发布者管理页面。

2. 使用你在上一节中创建个人访问令牌时使用的同一个 Microsoft 账户登录。

3. 点击左侧面板中的 Create publisher（创建发布者）。

4. 在新页面中，指定新发布者的必填参数——标识符和名称（分别为 ID 和 Name 字段）

   • ID：你在市场中发布者的唯一标识符，将用于你的扩展 URL。ID 一旦创建便无法更改。
   • Name：你在市场中发布者的唯一名称，将随你的扩展一起显示。可以是你的公司或品牌名称。

   以下是 Python 扩展的发布者标识符和名称示例

   

5. 根据需要填写其余字段。

6. 点击 Create（创建）

7. 使用 vsce 验证刚创建的发布者。在终端中运行以下命令，并在系统提示时输入上一步创建的个人访问令牌

   vsce login <publisher id>
   
   https://marketplace.visualstudio.com/manage/publishers/
   Personal Access Token for publisher '<publisher id>': ****************************************************
   
   The Personal Access Token verification succeeded for the publisher '<publisher id>'.
   

验证成功后，即可准备发布扩展。

发布扩展

你可以通过两种方式发布扩展

1. 自动方式，使用 vsce publish 命令

   vsce publish
   

   如果你还没有通过上述 vsce login 命令提供个人访问令牌，vsce 会提示你输入。

2. 手动方式，使用 vsce package 将扩展打包为可安装的 VSIX 格式，然后上传到 Visual Studio 市场发布者管理页面

   

查看扩展安装量和评分

Visual Studio 市场发布者管理页面可以让你查看每个扩展随时间变化的获取趋势，以及总获取次数和评分与评论。要查看报告，请点击扩展或选择 More Actions > Reports（更多操作 > 报告）。

自动递增扩展版本

发布扩展时，你可以通过指定要递增的 SemVer 兼容版本号（major、minor 或 patch）来自动递增版本号。例如，将扩展版本从 1.0.0 更新到 1.1.0，你需要指定

vsce publish minor

或

vsce publish 1.1.0

这两个命令都会先修改扩展的 package.json 中的 version 属性，然后使用更新后的版本进行发布。

取消发布扩展

你可以通过 Visual Studio 市场发布者管理页面点击 More Actions > Unpublish（更多操作 > 取消发布）来取消发布扩展

一旦取消发布，扩展的可用性状态将变为 Unpublished（已取消发布），它将不再能从市场和 Visual Studio Code 中下载

移除扩展

你可以通过两种方式移除扩展

1. 自动方式，使用 vsce 的 unpublish 命令

   vsce unpublish <publisher id>.<extension name>
   

2. 手动方式，从 Visual Studio 市场发布者管理页面点击 More Actions > Remove（更多操作 > 移除）

   

在这两种情况下，系统都会提示你通过输入扩展名称来确认移除操作。请注意，移除操作是不可逆的。

弃用扩展

你可以直接弃用一个扩展，或者为了替换为另一个扩展或设置而弃用。弃用的扩展在 UI 中将显示为带有删除线的暗色文本

每个弃用的扩展在扩展图标的右下角都有一个黄色警告图标（见上图截图）。将鼠标悬停在扩展图标上，你可以查看到弃用详情，无论是

• 该扩展被弃用且没有任何替代品

  

• 该扩展被弃用以支持另一个扩展

  

• 该扩展被弃用以支持一个设置

  

VS Code 不会自动迁移或卸载已安装的弃用扩展。如果弃用的扩展有替代扩展或设置，VS Code 将显示一个 Migrate（迁移）按钮，帮助你快速切换到指定的替代方案

要将你的扩展标记为已弃用，请在 Deprecated extensions 讨论帖中发表评论。

打包扩展

你可以选择在以下情况下打包你的扩展

• 在你的 VS Code 实例上进行测试。
• 在不发布到市场的情况下分发它。
• 私下与他人共享。

打包意味着创建一个包含你扩展的 .vsix 文件。此文件随后可安装在 VS Code 中。一些扩展会将 .vsix 文件作为 GitHub 发布版本的一部分进行发布。

要打包扩展，请在扩展的根文件夹中运行以下命令

vsce package

此命令会在你的扩展根文件夹中创建一个 .vsix 文件。例如：my-extension-0.0.1.vsix。

对于用户，要在 VS Code 中安装 .vsix 文件

• 从 VS Code 的“扩展”视图中

  1. 转到“扩展”视图。
  2. 选择 Views and More Actions...（视图与更多操作...）
  3. 选择 Install from VSIX...（从 VSIX 安装...）

• 从命令行

  # if you use VS Code
  code --install-extension my-extension-0.0.1.vsix
  
  # if you use VS Code Insiders
  code-insiders --install-extension my-extension-0.0.1.vsix
  

你的扩展文件夹

要加载扩展，你需要将文件复制到你的 VS Code 扩展文件夹 .vscode/extensions 中。根据你的操作系统，该文件夹的位置会有所不同

• Windows： %USERPROFILE%\.vscode\extensions
• macOS： ~/.vscode/extensions
• Linux： ~/.vscode/extensions

Visual Studio Code 兼容性

编写扩展时，必须指定扩展兼容的 VS Code 版本。为此，请在 package.json 中使用 engines.vscode 属性

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

• 1.8.0 的值（无插入符号）表示你的扩展仅与 VS Code 1.8.0 兼容。
• ^1.8.0 的值表示你的扩展与 VS Code 1.8.0 及更高版本兼容，包括 1.8.1、1.9.0 等。

你可以使用 engines.vscode 属性来确保扩展仅安装在包含你所依赖 API 的客户端上。该机制在稳定版和预览版（Insiders）中均表现良好。

例如，假设最新的 VS Code 稳定版是 1.8.0。在开发 1.9.0 版本期间，引入了一个新 API 并通过 1.9.0-insider 版本在预览版中提供。如果你想发布一个利用此 API 的扩展版本，应指明版本依赖为 ^1.9.0。这样，你的新扩展版本将仅在 VS Code >=1.9.0（换句话说，使用当前预览版的用户）上可用。拥有 VS Code 稳定版的用户只有在稳定版达到 1.9.0 时才会收到更新。

高级用法

市场集成

你可以自定义扩展在 Visual Studio 市场中的显示效果。查看 Go 扩展获取示例。

以下是让你的扩展在市场上看起来很棒的一些建议

• 在扩展根目录下添加一个 README.md 文件，其中包含你想在市场扩展页面上显示的内容。

  注意

  如果你的 package.json 中有指向公共 GitHub 仓库的 repository 属性，vsce 将自动检测它并相应地调整相对链接，默认使用 main 分支。在运行 vsce package 或 vsce publish 时，你可以使用 --githubBranch 标志覆盖此设置。你还可以使用 --baseContentUrl 和 --baseImagesUrl 标志设置链接和图像的基准 URL。

• 在扩展根目录下添加一个 LICENSE 文件，其中包含有关扩展许可的信息。

• 在扩展根目录下添加一个 CHANGELOG.md 文件，其中包含有关扩展变更历史的信息。

• 在扩展根目录下添加一个 SUPPORT.md 文件，其中包含如何获取扩展支持的信息。

• 通过 package.json 中的 galleryBanner.color 属性指定相应的十六进制值，设置市场页面上的横幅背景颜色。

• 通过 package.json 中的 icon 属性，指定扩展中包含的至少 128x128px PNG 文件的相对路径，以设置图标。

更多信息请参见 市场展示建议。

验证发布者

你可以通过验证与你的品牌或身份相关的合格域名的所有权，成为已验证发布者。发布者身份验证后，市场将在你的扩展详情页添加一个已验证徽章。

先决条件

要成为已验证发布者，必须在 VS 市场上拥有一个或多个扩展至少 6 个月，并且域名的注册时间也必须至少为 6 个月。请在满足这些标准后再申请验证。

验证发布者步骤

1. 前往 Visual Studio 市场发布者管理页面。

2. 在左侧面板中，选择或创建你希望验证的发布者。

3. 在主面板中，选择 Details（详情）选项卡。

   

4. 在 Details 选项卡的 Verified domain（已验证域名）部分下，输入一个合格域名。

   

   注意：开始输入后，你会注意到 Details 选项卡标题旁边有一个星号 (*)。就像在 VS Code 中一样，这表示有未保存的更改。因此，Verify（验证）按钮暂时是禁用的。

5. 选择 Save（保存），然后点击 Verify（验证）。

   

   将弹出一个对话框，为你提供有关将 TXT 记录添加到域名 DNS 配置的说明。

   

6. 按照说明将 TXT 记录添加到你的域名 DNS 配置中。

7. 在对话框中选择 Verify，以验证 TXT 记录已成功添加。

   

   TXT 记录验证通过后，市场团队将在 5 个工作日内审核你的请求并通知结果。验证包括但不限于：域名、网站和扩展的业绩前提条件、内容资格、合法性、信任度和正面声誉。

如果验证通过，你将在 Visual Studio 市场发布者管理页面看到发布者名称旁边出现相应的徽章

备注:

• 对发布者显示名称的任何更改都将撤销该已验证徽章。
• 任何未来的使用条款违规或上述验证违规行为，都将撤销该已验证徽章。

合格域名

合格域名必须满足以下条件

• 你必须能够管理 DNS 配置设置并添加 TXT 记录。
• 它不能是子域名（{subdomain}.github.io, {subdomain}.contoso.com 等）。
• 必须使用 HTTPS 协议。
• 必须能够对 HEAD 请求响应 HTTP 200 状态码。

扩展定价标签

你可以选择在扩展的市场页面上显示定价标签，以表明其为 Free（免费）或 Free Trial（免费试用）。

要显示定价标签，请在 package.json 中添加 pricing 属性。例如

{
  "pricing": "Free"
}

允许的值为：Free 和 Trial（区分大小写）。如果未指定 pricing 属性，默认值为 Free。

扩展赞助

你可以选择开启赞助功能，让用户有机会支持你的工作。

要显示赞助链接，请在 package.json 中添加 sponsor 属性。例如

"sponsor": {
  "url": "https://github.com/sponsors/nvaccess"
}

赞助链接将出现在你的扩展市场页面以及 VS Code 扩展详情标题中

我们希望这能让用户资助他们所依赖的扩展，从而提升扩展的性能、可靠性和稳定性。

使用 .vscodeignore

你可以创建 .vscodeignore 文件来阻止某些文件被包含在扩展包中。此文件是一个 glob 模式集合，每行一个。例如

**/*.ts
**/tsconfig.json
!file.ts

你应该忽略所有运行时不需要的文件。例如，如果你的扩展是使用 TypeScript 编写的，你应该像上面的示例一样忽略所有 **/*.ts 文件。

发布前步骤

你可以在清单文件中添加一个发布前步骤（pre-publish step），每次打包扩展时都会调用它。例如，你可能需要在此时调用 TypeScript 编译器

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}

预发布版扩展

用户可以在 VS Code 或 VS Code Insiders 中安装扩展的预发布版本，以便在官方正式发布前定期获取最新的扩展版本。

要发布预发布版本，请在 vsce package 或 vsce publish 命令中传递 --pre-release 标志

vsce package --pre-release
vsce publish --pre-release

扩展版本仅支持 major.minor.patch 格式，不支持 semver 预发布标签。预发布版本和正式版本之间的版本号必须不同。也就是说，如果 1.2.3 被上传为预发布版本，下一个正式版本必须使用不同的版本号上传，例如 1.2.4。未来将支持完整的 semver。

VS Code 会自动将扩展更新到可用的最高版本，因此即使某个用户选择了预发布版本，只要有一个版本号更高的正式版发布，该用户也会被更新到正式版本。因此，我们建议扩展使用 major.EVEN_NUMBER.patch 作为正式版，使用 major.ODD_NUMBER.patch 作为预发布版。例如：0.2.* 用于正式版，0.3.* 用于预发布版。

如果扩展作者不希望预发布用户被更新到正式版本，建议在发布正式版本之前，始终递增并发布一个新的预发布版本，以确保预发布版本号始终更高。注意，虽然预发布用户在正式版版本号更高时会被更新，但他们仍然有资格自动更新到版本号高于正式版的未来预发布版本。

预发布扩展在 VS Code 1.63.0 版本之后受支持，因此所有预发布扩展都应在 package.json 中将 engines.vscode 值设置为 >= 1.63.0。

平台特定扩展

你可以针对运行 VS Code 的每个平台（Windows、Linux、macOS）发布扩展的 VSIX 包。我们将此类扩展称为平台特定扩展。

从版本 1.61.0 开始，VS Code 会寻找与当前平台匹配的扩展包。

如果你的扩展包含特定平台的库或依赖项，平台特定扩展非常有用，这样你可以控制包含在平台包中的具体二进制文件。一个常见的用例是使用原生 node 模块。

平台特定扩展作为包含特定内容的分离包发布。你可以通过传递 --target 标志来指定目标平台。如果不传递此标志，该包将被用作没有特定平台包的所有平台的备用包。

当前支持的平台包括：win32-x64, win32-arm64, linux-x64, linux-arm64, linux-armhf, alpine-x64, alpine-arm64, darwin-x64, darwin-arm64 和 web。

如果你希望平台特定扩展也能作为网页扩展在浏览器中运行，发布时必须指定 web 平台。web 平台遵循 package.json 中的 browser 入口点。为了禁用在 web 中不支持的扩展功能，我们建议在 package.json 中使用 when 子句，而不是为 Web 平台单独提供 package.json 或删除 VSIX 中在 web 下无法运行的部分。

发布

从 1.99.0 版本开始，vsce 支持 --target 参数，允许你在打包和发布 VSIX 时指定目标平台。

以下是如何为 win32-x64 和 win32-arm64 平台发布 VSIX 的方法

vsce publish --target win32-x64 win32-arm64

或者，你也可以在打包时使用 --target 标志创建平台特定的 VSIX。例如，要为 win32-x64 平台打包 VSIX，然后进行发布

vsce package --target win32-x64
vsce publish --packagePath PATH_TO_WIN32X64_VSIX

持续集成

管理多个平台特定的 VSIX 可能会不堪重负，因此我们建议使用持续集成 (CI) 工具实现扩展构建过程的自动化。例如，你可以使用 GitHub Actions 来构建你的扩展。我们的平台特定扩展示例可作为学习起点：其工作流实现了使用平台特定扩展支持来跨所有受支持的 VS Code 目标分发原生 node 模块作为依赖项这一常见场景。

后续步骤

• 扩展市场 - 了解更多关于 VS Code 公共扩展市场的信息。
• 测试扩展 - 为你的扩展项目添加测试，以确保高质量。
• 打包扩展 - 通过使用 webpack 打包扩展文件来缩短加载时间。

常见问题

尝试发布扩展时出现“You exceeded the number of allowed tags of 30”错误？

Visual Studio 市场不允许扩展包在 package.json 中拥有超过 30 个 keywords。将关键字/标签数量限制在 30 个以内以避免此错误。

尝试发布扩展时出现 403 Forbidden（或 401 Unauthorized）错误？

创建个人访问令牌 (PAT) 时一个常见的错误是在 Organizations 字段下拉菜单中选择了特定组织，而不是 All accessible organizations。另一个可能的错误是作用域不正确——为了使发布正常工作，你应该将授权作用域设置为 Marketplace (Manage)。

我无法通过 vsce 工具取消发布我的扩展？

你可能更改了扩展 ID 或发布者 ID。你也可以直接通过 Visual Studio 市场发布者管理页面管理你的扩展。例如，更新或取消发布。

为什么 vsce 不保留文件属性？

请注意，在 Windows 上构建和发布扩展时，包含在扩展包中的所有文件都将缺乏 POSIX 文件属性，即执行权限位。一些 node_modules 依赖项依赖这些属性才能正常运行。从 Linux 和 macOS 发布工作正常。

我可以从持续集成 (CI) 构建中发布吗？

是的，请查看持续集成主题中的自动发布部分，了解如何配置 Azure DevOps、GitHub Actions 和 GitLab CI 以自动将你的扩展发布到市场。

尝试发布扩展时出现“ERROR The extension 'name' already exists in the Marketplace”错误？

市场要求每个扩展的扩展名称必须唯一。如果市场中已存在同名扩展，你将收到以下错误

ERROR The extension 'name' already exists in the Marketplace.

同样的规则也适用于扩展的显示名称。

支持哪些包管理器？

你可以使用 npm 或 yarn v1 来管理扩展的依赖项。

我需要关于 VS 市场账户的帮助或发布扩展的支持？

你可以通过登录 Manage Publishers & Extensions 并点击右上角的“Contact Microsoft”链接联系 VS 市场支持团队。