现已发布！阅读关于 11 月的新功能和修复。

发布扩展

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

本主题涵盖

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 作为其 Marketplace 服务。这意味着扩展的身份验证、托管和管理都通过 Azure DevOps 提供。

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

获取个人访问令牌

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

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

    Personal settings menu

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

    Create new token button

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

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

    Create personal access token

  4. 单击创建。

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

创建发布者

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

要创建发布者

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

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

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

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

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

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

    Example of publisher identifier and name

  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 Marketplace 发布者管理页面

    Add an extension through management page

查看扩展安装和评分

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

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

Unpublished extension

注意： 当你取消发布扩展时，Marketplace 将保留扩展统计信息。

删除扩展

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

  1. 自动，使用vsce 和 unpublish 命令

    vsce unpublish <publisher id>.<extension name>

  2. 手动，从 Visual Studio Marketplace 发布者管理页面通过单击更多操作 > 删除

    Remove the extension via the Marketplace management page

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

注意：当你取消发布扩展时，Marketplace 将删除任何扩展统计信息。你可能希望更新你的扩展，而不是取消发布它。

弃用扩展

您可以选择弃用一个扩展，或者选择弃用并推荐使用另一个扩展或设置。已弃用的扩展将在 UI 中以灰色删除线文本呈现。

Rust extension shown as deprecated in extension search

每个已弃用的扩展在扩展磁贴的右下角都有一个黄色警告图标（请参见上面的屏幕截图）。当您将鼠标悬停在扩展磁贴上时，您可以在此图标旁边看到弃用详细信息，无论：

  • 该扩展在没有任何替代方案的情况下被弃用

    Deprecated extension without alternatives

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

    Deprecated extension with an alternative extension

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

    Deprecated extension with an alternative setting

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

Deprecated extension with a migrate button

要将您的扩展标记为已弃用，请在已弃用的扩展讨论主题中留下评论。

注意： 目前，扩展程序在 Marketplace 中不会呈现为已弃用。此功能将在稍后提供。

打包扩展

如果您愿意，可以选择打包您的扩展程序

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

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

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

vsce package

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

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

  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 的客户端安装。此机制与 Stable 和 Insiders 版本都兼容。

例如，假设 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 Stable 的用户只有在稳定版本达到 1.9.0 版本时才会获得更新。

高级用法

Marketplace 集成

您可以自定义您的扩展程序在 Visual Studio Marketplace 中的外观。有关示例，请参阅Go 扩展程序。

以下是一些使您的扩展程序在 Marketplace 上看起来很棒的技巧

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

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

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

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

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

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

  • 通过在 package.json 中指定一个相对路径，指向您的扩展程序中包含的 128x128 像素 PNG 文件来设置图标。

有关更多信息，请参阅Marketplace 展示技巧。

验证发布者

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

先决条件

要成为已验证的发布者，发布者必须在 VS Marketplace 上拥有一个或多个扩展程序至少 6 个月，并且域名的注册也必须至少有 6 个月的历史。请等到满足这些条件后再申请验证。

Verified publisher indicators in VS Code

要验证发布者

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

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

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

    Publisher details tab location

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

    Publisher details tab with provided domain to verify

    注意：在您开始键入后，请注意 详细信息 选项卡标题旁边会出现一个星号 (*)。就像在 VS Code 中一样，这表示您有未保存的更改。出于同样的原因，验证 按钮也被禁用。

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

    Saved domain to verify

    将出现一个对话框窗口，其中提供有关向域名的 DNS 配置添加 TXT 记录的说明。

    TXT record verification

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

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

    Validation submitted

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

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

Verified publisher manage

注意:

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

合格域名

合格域名满足以下条件

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

扩展程序定价标签

您可以选择在您的扩展程序的 Marketplace 页面上显示一个定价标签，以表明它是 免费 或 免费试用。

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

{
  "pricing": "Free"
}

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

注意： 确保在发布您的扩展程序时使用 vsce 版本 >= 2.10.0，以便定价标签正常工作。

扩展程序赞助

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

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

"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

要发布预发布版本，请将 --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.偶数.patch 作为发布版本，使用 major.奇数.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 中的 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 捆绑扩展文件来缩短加载时间。

常见问题

当我尝试发布扩展时，出现“你超出了允许的 10 个标签数量”错误？

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

当我尝试发布扩展时，出现 403 禁止（或 401 未授权）错误？

创建 PAT（个人访问令牌）时容易犯的一个错误是在组织字段下拉列表中选择特定的组织，而不是所有可访问的组织。另一个可能出现的错误是范围不正确 - 你应该将授权范围设置为 Marketplace (管理) 以便发布工作。

我无法通过 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.

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

支持哪些包管理器？

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

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

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

12/11/2024