编辑

发布扩展

Name: Visual Studio Code
Author: Microsoft

制作出高质量的扩展后，你可以将其发布到 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。

发布扩展

注意

出于安全考虑，vsce 不会发布包含用户提供的 SVG 图像的扩展。

发布工具检查以下限制：

package.json 中提供的图标不能是 SVG。
package.json 中提供的徽章不能是 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 中创建你自己的组织。在以下示例中，组织名称为 vscode，你应该根据需要使用你的新组织名称。请注意，组织名称不一定需要与你的发布者名称相同。

从你的组织主页（例如：https://dev.azure.com/vscode），打开个人资料图片旁的用户设置下拉菜单，选择 Personal access tokens（个人访问令牌）。
在 Personal Access Tokens 页面，选择 New Token（新建令牌）。
在创建新个人访问令牌的模态窗口中，为令牌选择以下详细信息：
- 名称：你希望为令牌设置的任何名称。
- 组织：所有可访问的组织。
- 过期时间（可选）：设置令牌的所需过期日期。
- 范围：自定义定义。
  - 点击 Scopes（范围）部分下方的 Show all scopes（显示所有范围）链接。
  - 在范围列表中，滚动到 Marketplace（市场）并选择 Manage（管理）范围。
点击 Create（创建）。

你将看到新创建的个人访问令牌。复制它到安全位置，你将需要它来创建发布者。

创建发布者

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

要创建发布者：

前往 Visual Studio Marketplace 发布者管理页面。
使用与你在上一节中创建个人访问令牌时相同的 Microsoft 帐户登录。
在左侧窗格中点击 Create publisher（创建发布者）。
在新页面中，指定新发布者的强制参数 - 标识符和名称（分别为 ID 和 Name 字段）。
- ID：你在市场中的发布者的唯一标识符，将用于你的扩展 URL。ID 一旦创建就无法更改。
- 名称：你在市场中与你的扩展一起显示的发布者的唯一名称。这可以是你的公司或品牌名称。
以下是 Python 扩展的发布者标识符和名称示例：
（可选）填写其余字段。
点击 Create（创建）。

使用 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>'.

验证成功后，你就可以发布扩展了。

发布扩展

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

自动地，使用 vsce publish 命令。
```
vsce publish
```
如果你尚未通过上述 vsce login 命令提供个人访问令牌，vsce 将会要求你提供。
手动地，使用 vsce package 将扩展打包成可安装的 VSIX 格式，然后将其上传到 Visual Studio Marketplace 发布者管理页面。

查看扩展安装和评分

Visual Studio Marketplace 发布者管理页面允许你访问每个扩展随时间变化的获取趋势，以及总获取量和评分与评论。要查看报告，请点击扩展或选择 更多操作 > 报告。

Marketplace extension report

自动递增扩展版本

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

vsce publish minor

或者

vsce publish 1.1.0

这两个命令都将首先修改扩展的 package.json version 属性，然后用更新的版本发布它。

注意

如果你在 git 仓库中运行 vsce publish，它还将通过 npm-version 创建一个版本提交和标签。默认的提交消息将是扩展的版本，但你可以使用 -m 标志提供自定义提交消息。（当前版本可以在提交消息中用 %s 引用）。

取消发布扩展

你可以从 Visual Studio Marketplace 发布者管理页面取消发布扩展，点击 更多操作 > 取消发布。

Unpublish the extension via the Marketplace management page

取消发布后，扩展的可用性状态将更改为 Unpublished（未发布），并且将不再可从 Marketplace 和 Visual Studio Code 下载。

Unpublished extension

注意

当你取消发布扩展时，Marketplace 会保留扩展的统计数据。

移除扩展

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

自动地，使用 vsce 的 unpublish 命令。

vsce unpublish <publisher id>.<extension name>

手动地，从 Visual Studio Marketplace 发布者管理页面，点击 更多操作 > 移除。

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

注意

当你移除扩展时，Marketplace 也会移除所有扩展统计数据。你可能希望取消发布扩展而不是移除它。

弃用扩展

你可以选择弃用一个扩展，或者弃用并推荐另一个扩展或一个设置。被弃用的扩展将在用户界面中以暗淡的删除线文本呈现。

Rust extension shown as deprecated in extension search

每个被弃用的扩展在其扩展磁贴的右下角都有一个黄色警告图标（参见上图）。将鼠标悬停在扩展磁贴上时，你可以在此图标旁边看到弃用详情，无论是：

该扩展已弃用，没有替代品。
该扩展已弃用，取而代之的是另一个扩展。
该扩展已弃用，取而代之的是一个设置。

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

要将你的扩展标记为已弃用，请在 Deprecated extensions 讨论串中留言。

注意

目前，扩展在 Marketplace 中不会显示为已弃用。此功能将在稍后提供。

打包扩展

如果你希望，可以选择打包你的扩展：

在你的 VS Code 实例上测试它。
分发它而不发布到 Marketplace。
私下与他人分享。

打包意味着创建一个包含你的扩展的 .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 的客户端。此机制在稳定版和内测版发布中都能很好地发挥作用。

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

高级用法

市场集成

你可以自定义你的扩展在 Visual Studio Marketplace 中的显示方式。查看 Go 扩展作为示例。

以下是一些让你的扩展在 Marketplace 上看起来很棒的技巧：

在您的扩展程序的根目录添加一个 README.md 文件，其中包含您想要在扩展程序的 Marketplace 页面上显示的内容。

注意
在你的扩展根目录中添加一个 LICENSE 文件，其中包含有关扩展许可证的信息。
在你的扩展根目录中添加一个 CHANGELOG.md 文件，其中包含有关扩展更改历史的信息。
在你的扩展根目录中添加一个 SUPPORT.md 文件，其中包含有关如何获取扩展支持的信息。
通过在 package.json 中指定 galleryBanner.color 属性的相应十六进制值，设置 Marketplace 页面上的横幅背景颜色。
通过在 package.json 中指定 icon 属性的相对路径到包含在你的扩展中的至少 128x128px 的 PNG 文件来设置图标。
通过在 package.json 中指定 icon 属性的相对路径到包含在你的扩展中的至少 128x128px 的 PNG 文件来设置图标。

在 Marketplace 展示技巧中查看更多信息。

验证发布者

你可以通过验证与你的品牌或身份关联的合格域名的所有权，成为已验证发布者。一旦你的发布者被验证，Marketplace 将在你的扩展详细信息中添加一个已验证徽章。

先决条件

要获得验证，发布者必须在 VS Marketplace 上拥有一个或多个扩展至少 6 个月，并且域名的注册时间也必须至少为 6 个月。请等待这些条件满足后再申请验证。

Verified publisher indicators in VS Code

要验证发布者：

前往 Visual Studio Marketplace 发布者管理页面。
在左侧窗格中，选择或创建你希望验证的发布者。
在主窗格中，选择 Details（详细信息）选项卡。
在 Details tab（详细信息选项卡）中，在 Verified domain（已验证域名）部分下，输入一个合格域名。

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

将出现一个对话窗口，为你提供关于在你的域名的 DNS 配置中添加 TXT 记录的说明。
按照说明在你的域名的 DNS 配置中添加 TXT 记录。
在对话窗口中选择 Verify（验证），以验证 TXT 记录是否已成功添加。

一旦你的 TXT 记录通过验证，Marketplace 团队将在 5 个工作日内审核你的请求并告知你结果。验证包括但不限于：域名、网站和扩展的先决条件记录、内容资格、合法性、信任和良好声誉。

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

Verified publisher manage

注意事项:

对发布者显示名称的任何更改都将撤销已验证徽章。

发布者未来任何违反使用条款或上述验证的行为都将撤销已验证徽章。

合格域名

合格域名符合以下条件：

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

扩展定价标签

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

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

{
  "pricing": "Free"
}

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

注意

发布扩展时，请确保使用 vsce 版本 >= 2.10.0，以使定价标签生效。

你可以选择赞助，让用户支持你的工作。

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

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

注意

发布扩展时，请确保使用 vsce 版本 >= 2.9.1，以使赞助功能生效。

赞助链接将显示在你的扩展的 Marketplace 页面和 VS Code 的扩展详细信息标题中。

Sponsor link in extension details page

我们希望这将允许我们的用户资助他们所依赖的扩展，以提高扩展的性能、可靠性和稳定性。

使用 .vscodeignore

你可以创建一个 .vscodeignore 文件，以防止某些文件包含在你的扩展包中。该文件是一系列 glob 模式的集合，每行一个。例如：

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

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

注意

devDependencies 中列出的开发依赖项将自动被忽略，因此你无需显式添加它们。

预发布步骤

你可以在清单文件中添加一个预发布步骤，每次打包扩展时都会调用该步骤。例如，你可能希望在此阶段调用 TypeScript 编译器。

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

预发布扩展

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

GitHub PR extension pre-release version in the extensions view

要发布预发布版本，请向 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 团队以启用自动卸载过时的单独扩展并安装主扩展的预发布版本。

平台特定扩展

你可以为 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 来构建你的扩展。我们的平台特定扩展示例可以作为学习的起点：它的工作流实现了使用平台特定扩展支持将原生 Node 模块作为依赖项分发到所有支持的 VS Code 目标的常见场景。

下一步

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

常见问题

当我尝试发布我的扩展时，收到“您超出了允许的 30 个标签的数量”错误？

Visual Studio Marketplace 不允许扩展包在 package.json 中拥有超过 30 个 keywords。请将关键词/标签的数量限制在最多 30 个，以避免此错误。

当我尝试发布我的扩展时，收到 403 Forbidden（或 401 Unauthorized）错误？

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

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

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

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

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

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

是的，请参阅持续集成主题的自动发布部分，了解如何配置 Azure DevOps、GitHub Actions 和 GitLab CI 来自动将您的扩展发布到 Marketplace。

当我尝试发布我的扩展时，收到“错误：扩展‘名称’已存在于 Marketplace 中”的错误？

Marketplace 要求每个扩展的扩展名称都是唯一的。如果 Marketplace 中已存在同名扩展，你将收到以下错误：

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

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

支持哪些包管理器？

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

我的 VS Marketplace 帐户有问题，或者发布扩展需要支持？

你可以登录管理发布者和扩展，然后点击右上角的“联系 Microsoft”链接，联系 VS Marketplace 支持团队。

06/12/2025

发布扩展

vsce

安装

用法

发布扩展

获取个人访问令牌

创建发布者

发布扩展

查看扩展安装和评分

自动递增扩展版本

取消发布扩展

移除扩展

弃用扩展

打包扩展

你的扩展文件夹

Visual Studio Code 兼容性

高级用法

市场集成

验证发布者

先决条件

合格域名

扩展定价标签

扩展赞助

使用 .vscodeignore

预发布步骤

预发布扩展

平台特定扩展

发布

持续集成

下一步

常见问题

当我尝试发布我的扩展时，收到“您超出了允许的 30 个标签的数量”错误？

当我尝试发布我的扩展时，收到 403 Forbidden（或 401 Unauthorized）错误？

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

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

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

当我尝试发布我的扩展时，收到“错误：扩展‘名称’已存在于 Marketplace 中”的错误？

支持哪些包管理器？

我的 VS Marketplace 帐户有问题，或者发布扩展需要支持？

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