发布扩展

开发出高质量的扩展后，您可以将其发布到 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 中提供的徽章不能是 SVG，除非它们来自受信任的徽章提供商。
• README.md 和 CHANGELOG.md 中的图像 URL 需要解析为 https URL。
• README.md 和 CHANGELOG.md 中的图像不能是 SVG，除非它们来自受信任的徽章提供商。

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

vsce 只能使用个人访问令牌发布扩展。您需要至少创建一个个人访问令牌才能发布扩展。

获取个人访问令牌

首先，按照文档在 Azure DevOps 中创建您自己的组织。在以下示例中，组织名称为 vscode，您应该使用您新的组织名称。请注意，组织名称不必与您的发布者名称相同。

1. 从您的组织主页（例如：https://dev.azure.com/vscode）中，打开个人资料图片旁边的用户设置下拉菜单，然后选择 个人访问令牌（Personal access tokens）。

   

2. 在个人访问令牌页面上，选择新建令牌（New Token）。

   

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

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

   

4. 点击创建（Create）。

   您将看到新创建的个人访问令牌。请将其复制到安全位置，创建发布者时需要用到它。

创建发布者

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

创建发布者

1. 转到Visual Studio 市场发布者管理页面。

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

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

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

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

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

   

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 版本属性，然后使用更新后的版本发布它。

取消发布扩展

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

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

移除扩展

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

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

   vsce unpublish <publisher id>.<extension name>
   

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

   

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

弃用扩展

您可以仅弃用一个扩展，或弃用并推荐另一个扩展或一个设置。弃用的扩展将在 UI 中以暗淡的删除线文本显示。

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

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

  

• 扩展被弃用，推荐另一个扩展

  

• 扩展被弃用，推荐一个设置

  

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

要将您的扩展标记为已弃用，请在已弃用扩展讨论帖中留言。

打包扩展

如果您希望执行以下操作，可以选择打包您的扩展

• 在您的 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. 选择从 VSIX 安装...（Install from 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 的客户端上。此机制适用于稳定版和 Insider 版本。

例如，假设 VS Code 的最新稳定版本是 1.8.0。在开发 1.9.0 版本期间，引入了一个新的 API，并通过版本 1.9.0-insider 在 Insider 版本中可用。如果您想发布一个利用此 API 的扩展版本，您应该指定版本依赖 ^1.9.0。通过这种方式，您的新扩展版本将仅在 VS Code >=1.9.0 上可用（换句话说，使用当前 Insider 版本的用户）。使用 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. 在详细信息选项卡中，在已验证域（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（免费试用）。

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

{
  "pricing": "Free"
}

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

扩展赞助

您可以选择加入赞助，为您的用户提供一种支持您工作的方式。

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

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

赞助链接将显示在您的扩展在市场和 VS Code 中的页面上的扩展详情头部。

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

使用 .vscodeignore

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

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

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

预发布步骤

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

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

预发布扩展

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

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

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。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 捆绑您的扩展文件来提高加载时间。

常见问题

我尝试发布扩展时收到“您超出了允许的标签数量 10”错误怎么办？

Visual Studio 市场不允许扩展包在 package.json 中拥有超过 10 个 keywords。将关键字/标签数量保持在 10 个以下即可避免此错误。

我尝试发布扩展时收到 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 市场帐户需要帮助或发布扩展需要支持怎么办？

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