现已发布！阅读 10 月份的新功能和修复。

发布扩展

创建高质量的扩展后，您可以将其发布到 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 提供其市场服务。这意味着扩展的认证、托管和管理通过 Azure DevOps 提供。

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

获取个人访问令牌

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

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

    Personal settings menu

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

    Create new token button

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

    • 名称：您要为令牌指定的任何名称
    • 组织：所有可访问组织
    • 过期时间（可选）：设置令牌的所需过期日期
    • 范围：自定义定义
      • 点击显示所有范围 链接，位于范围部分下方
      • 在范围列表中，滚动到市场，然后选择管理 范围

    Create personal access token

  4. 点击创建。

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

创建发布者

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

要创建发布者

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

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

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

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

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

    以下是 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 市场发布者管理页面

    Add an extension through management page

查看扩展安装和评分

Visual Studio 市场发布者管理页面 可让您访问每个扩展的获取趋势随时间的变化，以及总获取次数、评分和评论。要查看报告，请点击扩展或选择更多操作>报告。

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 市场发布者管理页面 中的更多操作>取消发布 从市场中取消发布扩展。

Unpublish the extension via the Marketplace management page

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

Unpublished extension

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

删除扩展

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

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

    vsce unpublish <publisher id>.<extension name>

  2. 手动，从 Visual Studio 市场发布者管理页面 中点击更多操作>删除

    Remove the extension via the Marketplace management page

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

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

弃用扩展

您可以选择弃用扩展，或者弃用以支持另一个扩展或设置。弃用扩展将在 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

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

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

打包扩展

如果您想要，可以选择打包您的扩展

  • 在您的 VS Code 实例中测试它。
  • 在不发布到市场的情况下分发它。
  • 与他人私下分享它。

打包意味着创建一个包含扩展的.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 的客户端上。这种机制与稳定版和内部版发布都能很好地配合。

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

高级用法

市场整合

您可以自定义扩展在 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 中的 icon 属性中指定指向扩展中包含的 128x128px PNG 文件的相对路径来设置图标。

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

验证发布者

您可以通过验证与您的品牌或身份相关的 合格域 的所有权来成为**已验证的发布者**。验证发布者后，Marketplace 将在您的扩展详细信息中添加已验证徽章。

先决条件

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

Verified publisher indicators in VS Code

要验证发布者

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

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

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

    Publisher details tab location

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

    Publisher details tab with provided domain to verify

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

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

    Saved domain to verify

    将出现一个对话框，提供有关将 TXT 记录添加到域的 DNS 配置的说明。

    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 协议。
  • 它必须能够对 HEAD 请求以 HTTP 200 状态进行响应。

扩展定价标签

您可以选择在扩展的 Marketplace 页面上显示定价标签，以指示它是 免费 还是 免费试用。

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

{
  "pricing": "Free"
}

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

**注意：**请确保在发布扩展时使用 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.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 会查找与当前平台匹配的扩展包。

如果您的扩展具有平台特定的库或依赖项，则平台特定扩展非常有用，因此您可以控制平台包中包含的确切二进制文件。一个常见的用例是使用 **原生节点模块**。

平台特定扩展作为包含平台特定内容的单独包发布。您可以通过传递 --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 目标中。

下一步

  • 扩展市场 - 了解有关 VS Code 的公共扩展市场的更多信息。
  • 测试扩展 - 为您的扩展项目添加测试以确保高质量。
  • 捆绑扩展 - 使用 webpack 捆绑您的扩展文件以提高加载速度。

常见问题

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

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

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

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

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

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

为什么 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 Marketplace 帐户的帮助，或者需要关于发布扩展的支持？

您可以通过在 管理发布者和扩展 中登录并点击右上角的“联系 Microsoft”链接来联系 VS Marketplace 支持团队。

10/29/2024