【译文】发布一个VS Code 扩展

原文链接： Publishing Extensions code.visualstudio.com/api/working...

一旦您制作了高质量的扩展，您可以将其发布到 VS Code 扩展市场，以便其他人可以找到、下载和使用您的扩展。或者，您可以将扩展打包为可安装的 VSIX 格式，并与其他用户共享。

本主题涵盖了以下内容：

• 使用 vsce，管理 VS Code 扩展的命令行工具
• 打包、发布和取消发布扩展
• 注册发布扩展所需的发布者

一、 vsce

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

1.2安装

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

npm install -g @vscode/vsce

1.2 使用

您可以使用 vsce 轻松打包和发布您的扩展：

$ cd myExtension
$ vsce package
# myExtension.vsix 生成
$ vsce publish
# <发布者 ID>.myExtension 发布到 VS Code 市场

vsce 还可以搜索、检索元数据和取消发布扩展。要查看所有可用的 vsce 命令的参考，请运行 vsce --help。

二、创建 Publishing extensions

注意：由于安全问题，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 只能使用个人访问令牌发布扩展。您需要创建至少一个才能发布扩展。

2.1 获取个人访问令牌

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

1. 从您组织的主页（例如：dev.azure.com/vscode），打开用户设置下拉菜单旁边的个人访问令牌：

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

3. 在新建个人访问令牌对话框中，选择令牌的以下详细信息：

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

4. 点击创建。 您将看到您新创建的个人访问令牌。将其复制到安全位置，您在创建发布者时会用到它。

2.2 创建发布者

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

要创建发布者：

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

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

3. 在左侧窗格中点击"Create publisher"。

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

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

以下是 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>'.

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

三、 发布扩展 Publish an extension

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

1. 自动使用 vsce publish 命令：

vsce publish

如果您尚未使用 vsce login 命令提供个人访问令牌，vsce 将要求您输入。

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

通过管理页面添加扩展

四、审阅扩展安装和评级

Visual Studio Marketplace 发布者管理页面可让您访问每个扩展的获取趋势、总获取计数和评级与评论。要查看报告，请点击扩展或选择 More Actions > Reports.。

市场扩展报告

五、自动增加扩展版本号

在发布扩展时，您可以通过指定符合 SemVer 的数字或版本（主要、次要或修订）来自动增加其版本号。例如，要将扩展的版本从 1.0.0 更新为 1.1.0，您可以指定：

vsce publish minor

或

vsce publish 1.1.0

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

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

六、取消发布扩展

您可以通过在 Visual Studio Marketplace 发布者管理页面点击"更多操作" > "取消发布" 来取消发布扩展：

通过市场管理页面取消发布扩展

一旦取消发布，扩展的可用状态将更改为"已取消发布"，并且将不再可以从市场和 Visual Studio Code 中下载：

取消发布的扩展

注意：取消发布扩展时，市场将保留扩展统计信息。

七、移除扩展

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

自动使用 vsce 的取消发布命令：

vsce unpublish <发布者 ID>.<扩展名称>

手动通过 Visual Studio Marketplace 发布者管理页面点击"更多操作" > "移除"：

通过市场管理页面删除扩展

在这两种情况下，系统将提示您确认删除扩展。注意，删除操作是不可逆转的。

注意：取消发布扩展时，市场将删除任何扩展统计信息。您可能希望更新扩展而不是取消发布扩展。

八、废弃扩展

您可以选择废弃一个扩展，或者废弃以支持另一个扩展或设置。已废弃的扩展将在 UI 中显示为带有变淡删除线的文本：

在扩展搜索中显示为已废弃的 Rust 扩展

每个已废弃的扩展在扩展磁贴的右下角都有一个黄色警告图标（请参见上图）。当悬停在扩展磁贴上时，您可以在此图标旁边看到废弃细节，无论是：

• 没有任何替代方案的已废弃扩展：
• 已废弃以支持另一个扩展：
• 已废弃以支持设置：

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

带迁移按钮的已废弃扩展

要将您的扩展标记为已废弃，请在已废弃扩展讨论帖子中留下评论。

注意：目前，市场中的扩展不会以已废弃的形式呈现。此功能将在以后提供。

九、打包扩展

如果您想要：

• 在您的 VS Code 实例上测试它。
• 分发它而不将其发布到市场。
• 私下与他人分享。

您可以选择打包您的扩展。打包意味着创建一个包含您的扩展的 .vsix 文件。然后，这个文件可以安装到 VS Code 中。一些扩展将 .vsix 文件作为其 GitHub 发布的一部分。

对于扩展作者，要打包扩展，请在您的扩展根文件夹中运行以下命令：

vsce package

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

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

• 转到"扩展"视图。
• 点击"视图"和"更多操作"...
• 选择"从 VSIX 安装"... 或者

在您的终端中，运行以下命令：

• 如果您使用 VS Code

code --install-extension my-extension-0.0.1.vsix

• 如果您使用 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 在 Insiders 版本中提供。如果您希望发布一个从此 API 中受益的扩展版本，您应该指定一个版本依赖性为 ^1.9.0。这样，您的新扩展版本将仅在 VS Code >=1.9.0（换句话说，使用当前 Insiders 版本的用户）上可用。只有当稳定版发布到 1.9.0 时，使用 VS Code 稳定版的用户才会获得更新。

十二、高级用法

市场集成

您可以自定义您的扩展在 Visual Studio Marketplace 上的外观。请参阅 Go 扩展以获取示例。

以下是使您的扩展在 Marketplace 上看起来更好的一些提示：

• 在扩展的根目录中的 README.md 文件将用于填充扩展的 Marketplace 页面内容。vsce 将为您以两种不同的方式修改 README 链接：
  • 如果您在 package.json 中添加了一个 repository 字段，并且它是一个公共 GitHub 仓库，vsce 将自动检测并据此调整相对链接，使用默认的 master 分支。您可以在运行 vsce package 或 vsce publish 时使用 --githubBranch 标志覆盖 GitHub 分支。
  • 对于更精细的控制，您可以设置 --baseContentUrl 和 --baseImagesUrl 标志，以设置相对链接的基本 URL。
• 扩展根目录中的 LICENSE 文件将用作扩展许可证的内容。
• 扩展根目录中的 CHANGELOG.md 文件将用作扩展的变更日志内容。
• 您可以通过在 package.json 中将 galleryBanner.color 设置为预期的十六进制值来设置横幅背景颜色。
• 您可以通过将 icon 设置为您的扩展中包含的一个 128px 正方形 PNG 文件的相对路径，在 package.json 中设置一个图标。

另请参阅 Marketplace Presentation Tips。

验证发布者

您可以通过验证与您的品牌或标识关联的符合条件的域名所有权来成为验证发布者。验证发布者将证明您的真实性，并为您的扩展添加一个已验证的徽标。

VS Code 中的已验证发布者指示器

要验证发布者：

• 访问 Visual Studio Marketplace 发布者管理页面。
• 选择或创建您希望验证的发布者。
• 在"eligible domain"字段中输入一个符合条件的域名，保存，并选择"验证"。
• 按照对话框中的说明在您域名的 DNS 配置中添加一个 TXT 记录。
• 选择"验证"，以验证 TXT 记录已成功添加。

一旦您的 TXT 记录已经被验证，Marketplace 团队将在 5 个工作日内审核您的请求并授予验证。

注意：更改发布者显示名称将撤销已验证徽标。

符合条件的域名

符合条件的域名需要满足以下条件：

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

扩展定价标签

您可以在 Marketplace 中为您的扩展添加定价标签，以指示它是免费的还是免费试用。

作为扩展作者，您可以通过将 pricing 字段添加到 package.json 中来选择在您的扩展页面上显示定价标签，例如：

{
  "pricing": "Free"
}

定价字段的值可以是 Free 或 Trial。请注意，这些值区分大小写。

如果您没有将 pricing 字段添加到 package.json 中，将默认显示免费标签。

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

扩展赞助商

扩展可以通过在其 package.json 中添加 sponsor 字段以及扩展作者希望使用的赞助链接的 url 字段来选择参与赞助。例如：

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

请注意：确保在发布扩展时使用 vsce 版本 >= 2.9.1，以使赞助生效。

如果扩展选择参与 VS Code 将在扩展详情页面标题中呈现一个赞助按钮。

扩展详情页面中的赞助按钮

我们希望这将使我们的用户有机会资助对扩展性能、可靠性和稳定性有所依赖的扩展。

使用 .vscodeignore

您可以创建一个 .vscodeignore 文件，以排除一些文件不包括在您的扩展包中。这个文件是一组 glob 模式，每行一个。

例如：

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

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

注意：在 devDependencies 中列出的开发依赖项将自动被忽略，您不需要将它们添加到 .vscodeignore 文件中。

预发布步骤

您可以向您的清单文件添加一个预发布步骤。每次打包扩展时都会调用该命令。

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

每次打包扩展时都会调用 TypeScript 编译器。

预发布扩展

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

GitHub PR 扩展在扩展视图中预发布版本

要发布预发布版本，需要在打包和发布步骤中传递一个预发布标志：

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

我们仅支持扩展版本的 major.minor.patch，不支持语义化版本的预发布标签。因此，如果您将 major.minor.patch-tag 发布到 Marketplace，它将被视为 major.minor.patch，并且标签将被忽略。预发布版本和常规版本之间的版本必须不同。也就是说，如果将 1.2.3 作为预发布版本上传，下一个常规版本必须上传一个不同的版本，例如 1.2.4。全面支持语义化版本将在将来到来。

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 平台。Web 平台将遵守 package.json 中的浏览器入口点。不支持 Web 中的扩展功能应该在 package.json 中使用 when 条件来确保它们被禁用。我们不建议扩展以不同的 package.json 发布到 Web 平台，或者删除在 Web 中不起作用的 VSIX 部分。

发布

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

以下是如何在 win32-x64 和 win32-arm64 平台发布 VSIX：

vsce publish --target win32-x64 win32-arm64

或者，您也可以在打包时使用 --target 选项简单地创建一个平台特定的 VSIX。然后可以像通常一样将 VSIX 发布到 Marketplace。以下是如何在 win32-x64 平台上执行此操作：

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

持续集成

管理多个平台特定的 VSIX 可能会变得很复杂，因此建议在持续集成中自动化您的扩展构建过程。使用 GitHub Actions 是一个良好的方法。

我们的平台特定扩展示例可以用作学习资源；它的工作流程可以实现使用平台特定的扩展支持将本机 node 模块作为依赖项在所有支持的 VS Code 目标中分发的常见场景。

下一步

• Extension Marketplace - 了解更多关于 VS Code 的公共扩展市场。
• Testing Extensions - 向您的扩展项目中添加测试，以确保高质量。
• Bundling Extensions - 通过使用 webpack 捆绑您的扩展文件来提高加载时间。

常见问题

• 当我尝试发布我的扩展时，我收到了"您超过了允许的标签数目 10"的错误？

  • Visual Studio Marketplace 不允许扩展包中有超过十个关键字。请确保关键字/标签数量少于 10 个，以避免此错误。

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

  • 创建个人访问令牌时一个常见错误是没有在组织字段下拉菜单中选择"所有可访问的组织"（而不是选择特定组织）。您还应该为发布设置授权范围为 Marketplace（Manage），以使发布工作。

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

  • 您可能已更改了您的扩展 ID 或发布者名称。您还可以通过转到管理页面直接管理您的扩展。您可以从发布者管理页面更新或取消发布您的扩展。

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

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

• 我可以从持续集成（CI）构建中发布吗？

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

• 当我尝试发布我的扩展时，我收到了"错误：扩展 'name' 已存在于 Marketplace 中"的错误？

  • Marketplace 要求每个扩展的扩展名是唯一的。如果 Marketplace 中已经存在同名的扩展，您将收到以下错误消息：

  错误：扩展 'name' 已存在于 Marketplace 中。 对扩展的显示名称也适用相同的规则。

希望这些信息能帮到您。如果有任何问题，欢迎继续提问！