发布扩展

一旦你创建了一个高质量的扩展，你可以将其发布到 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），打开个人资料图片旁边的用户设置下拉菜单，然后选择个人访问令牌

   

2. 在个人访问令牌页面上，选择新建令牌

   

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

   • 名称：你想要的任何令牌名称
   • 组织：所有可访问的组织
   • 过期时间（可选）：为令牌设置所需的过期日期
   • 作用域：自定义
     • 单击作用域部分下方的显示所有作用域链接
     • 在作用域列表中，滚动到市场并选择管理作用域

   

4. 单击创建。

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

创建发布者

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

创建发布者

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

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

3. 单击左侧窗格中的创建发布者。

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

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

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

   

5. 可选地，填写其余字段。

6. 单击创建

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 市场发布者管理页面让你能够查看每个扩展随时间的获取趋势，以及总获取量和评分 & 评论。要查看报告，请单击某个扩展或选择更多操作 > 报告。

自动递增扩展版本

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

vsce publish minor

或

vsce publish 1.1.0

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

取消发布扩展

你可以从 Visual Studio 市场发布者管理页面取消发布扩展，方法是单击更多操作 > 取消发布。

一旦取消发布，扩展的可用性状态将更改为未发布，并且它将不再可从市场和 Visual Studio Code 下载。

删除扩展

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

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

   vsce unpublish <publisher id>.<extension name>
   

2. 手动地，从 Visual Studio 市场发布者管理页面通过点击更多操作 > 移除。

   

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

弃用扩展

你可以直接弃用一个扩展，或者弃用它以支持另一个扩展或一个设置。弃用的扩展将在 UI 中以暗淡的删除线文本呈现。

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

• 扩展已被弃用，无替代方案

  

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

  

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

  

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

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

打包扩展

如果你想，可以选择打包你的扩展，以便

• 在你的 VS Code 实例上测试它。
• 无需发布到市场即可分发它。
• 私下与他人共享它。

打包意味着创建一个包含你的扩展的 .vsix 文件。然后可以在 VS Code 中安装此文件。有些扩展将 .vsix 文件作为其 GitHub 发布的一部分。

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

vsce package

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

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

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

  1. 转到“扩展”视图。
  2. 选择视图和更多操作...
  3. 选择从 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 中有一个 repository 属性指向公共 GitHub 仓库，vsce 将自动检测它并相应地调整相对链接，默认使用 main 分支。你可以在运行 vsce package 或 vsce publish 时使用 --githubBranch 标志覆盖此设置。你还可以使用 --baseContentUrl 和 --baseImagesUrl 标志为链接和图片设置基本 URL。

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

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

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

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

• 通过在 package.json 中指定 icon 属性，设置一个图标，该图标是包含在你的扩展中且至少为 128x128 像素的 PNG 文件的相对路径。

更多信息请参见市场展示技巧。

验证发布者

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

先决条件

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

验证发布者

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

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

3. 在主窗格中，选择详细信息选项卡。

   

4. 在详细信息选项卡的已验证域名部分下，输入一个合格域名。

   

   注意：开始输入后，请留意详细信息选项卡标题旁边的星号（*）。就像在 VS Code 中一样，这表示你有未保存的更改。出于同样的原因，验证按钮仍处于禁用状态。

5. 选择保存，然后选择验证。

   

   将出现一个对话窗口，为你提供关于将 TXT 记录添加到你的域名 DNS 配置的说明。

   

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

7. 在对话窗口中选择验证，以验证 TXT 记录是否已成功添加。

   

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

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

备注:

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

合格域名

合格域名需满足以下条件

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

扩展定价标签

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

要显示定价标签，请将 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 标志来指定目标平台。如果你不传递此标志，该包将用作所有没有平台特定包的平台的 fallback（备用）包。

当前可用的平台有：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 捆绑扩展文件来缩短加载时间。

常见问题

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

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

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

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

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

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

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

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

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

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

当我尝试发布我的扩展时，收到“错误 扩展 'name' 已存在于市场中”错误？

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

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

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

支持哪些包管理器？

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

我需要我的 VS 市场帐户方面的帮助或发布扩展方面的支持？

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