本站点文档内容均翻译自code.visualstudio.com，仅供个人学习，如有差异请以官网为准。

发布扩展

一旦你制作了一个高质量的扩展，你就可以将其发布到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 生成
$ vsce publish
# <publisher id>.myExtension 发布到 VS Code 市场

vsce还可以搜索、检索元数据并取消发布扩展。有关所有可用扩展的参考信息vsce命令，运行vsce --帮助输入：.

发布扩展

注意

由于安全问题，vsce不会发布包含用户提供的SVG图像的扩展。

发布工具检查以下约束条件：

  • 提供的图标package.json可能不是SVG。
  • 提供的徽章package.json 除非它们来自 可信的徽章提供商，否则可能不是 SVG。
  • 图像链接在自述文件.md和CHANGELOG.md需要解决到对不起，我无法访问特定的网页内容或链接。如果你能提供具体的文本内容，我可以帮助你进行翻译。网址。
  • 图片在自述文件.md和CHANGELOG.md 除非它们来自 可信的徽章提供商，否则可能不是 SVG。

Visual Studio Code 使用 Azure DevOps 为其市场服务提供支持。这意味着扩展的认证、托管和管理是通过 Azure DevOps 提供的。

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

获取个人访问令牌

您可以通过 Azure DevOps 门户创建个人访问令牌。要创建个人访问令牌：

  1. 如果你还没有 Azure DevOps 组织，请按照 创建一个组织 文章中的步骤操作。

  2. 前往Azure DevOps门户，并选择您的组织。

  3. 打开用户设置下拉菜单，位于您的头像旁边，并选择个人访问令牌：

    个人设置菜单

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

    创建新代币按钮

  5. 在创建新的个人访问令牌模式中，选择令牌的以下详细信息：

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

    创建个人访问令牌

  6. 点击 创建.

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

创建发布者

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

要创建一个发布者：

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

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

  3. 点击 创建发布者 在左侧的面板中。

  4. 在新页面中，指定新出版商的必需参数 - 标识符和名称（分别对应 ID 和 Name 字段）：

    • ID：这是您在市场中用于您的扩展网址的唯一标识符。ID 在创建后无法更改。
    • 名称：您的唯一出版商名称，该名称将在市场中与您的扩展一起显示。这可以是您的公司或品牌名称。

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

    出版商标识和名称示例

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

  6. 点击 创建

  7. 验证新创建的发布者使用vsce在您的终端中，运行以下命令，并在提示时输入上一步创建的个人访问令牌：

    vsce 登录 <发布者 我d>

https://marketplace.visualstudio.com/manage/publishers/
个人 访问 令牌 用于 发布者 '<发布者 id>': ****************************************************

个人访问令牌验证成功对于发布者'<发布者 id>'。

一旦验证通过，您就可以发布扩展。

发布扩展

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

  1. 自动地，使用vsce 发布命令:

    vsce 发布

    如果您还没有提供您的个人访问令牌vsce 登录命令如下，vsce会要求它的。

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

    通过管理页面添加扩展

评论扩展安装和评分

Visual Studio Marketplace发布者管理页面提供了每个扩展的长期获取趋势、总获取数量和评分与评论。要查看报告，请点击一个扩展或选择更多操作 > 报告。

市场扩展报告

自动递增扩展版本号

发布扩展时，您可以通过指定SemVer-兼容的数字或版本来自动增加其版本号 (主要，小的，或补丁) 增加。例如，将扩展版本从 1.0.0 更新到 1.1.0，您需要指定：

vsce 发布 小版本

或

vsce 发布 1.1.0

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

注意

如果你运行vsce 发布在git仓库中，它还会通过`npm-version`创建一个版本提交和标签。默认的提交信息将是扩展的版本，但你可以使用`--message`参数提供自定义的提交信息。-米旗帜。(当前版本可以从提交信息中引用)输入：%s)。

取消发布扩展

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

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

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

未发表的扩展

注意

当你取消发布一个扩展时，市场会保留扩展的统计数据。扩展仍然可以通过现有的 API 公开发现并使用。

移除扩展

您可以通过两种方式卸载扩展：

  1. 自动地，使用vsce与取消发布命令:

    vsce 取消发布 <发布者 我d>.<扩展 名e>

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

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

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

注意

当你移除一个扩展时，市场也会移除任何扩展统计数据。你可能想取消发布你的扩展，而不是移除它。

弃用扩展

您可以简单地弃用一个扩展，或者弃用某个扩展以 favor 于另一个扩展或一个设置。被弃用的扩展在用户界面中将以暗淡的划线文本呈现：

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

每个已弃用的扩展在扩展瓷砖的右下角都有一个黄色警告图标（见上面的截图）。当将鼠标悬停在扩展瓷砖上时，您可以在该图标旁边看到弃用详细信息，包括：

  • 该扩展已被弃用，没有替代方案：

    已弃用的没有替代品的扩展

  • 该扩展已被另一个扩展取代：

    已弃用的扩展与替代扩展

  • 该扩展已被弃用，取而代之的是一个设置：

    已弃用的扩展与替代设置

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

已弃用的扩展，带有迁移按钮

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

注意

目前，扩展在市场中不会显示为已弃用。此功能稍后会提供。

包装扩展

如果您愿意，您可以选择包装您的扩展：

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

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

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

vsce 包

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

对于用户，要安装一个.vsix在 VS Code 中打开文件:

  • 从 VS Code 的扩展视图：

    1. 转到扩展视图。
    2. 选择 视图和更多操作...
    3. 选择 从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/扩展. 根据您的操作系统，此文件夹的位置不同：

  • Windows: %USERPROFILE%\.vscode\extensions
  • macOS: ~/.vscode/扩展
  • Linux: ~/.vscode/扩展

Visual Studio Code 兼容性

在编写扩展时，您必须指定您的扩展兼容的 VS Code 版本。为此，请使用engines.vscode属性内部package.json输入：

{
  "engines": {
    "vscode": "^1.8.0"
  }
}
  • 一个值1.8.0（无标记）表示您的扩展仅兼容 VS Code1.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在Insider版本中引入并提供使用。1.9.0-insider如果你希望发布一个受益于此 API 的扩展版本，你应该表明一个版本依赖于^1.9.0通过这种方式，您的新扩展版本将仅在 VS Code 上可用>=1.9.0（换句话说，拥有当前Insiders发布版本的用户）。只有当Stable版本达到版本时，拥有VS Code Stable的用户才会收到更新。1.9.0输入：.

高级用法

市场整合

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

以下是一些让您的扩展在市场中看起来很棒的提示：

  • 添加一个自述文件.md将包含您希望在扩展的Marketplace页面上显示的内容的文件放置在扩展的根目录。

    注意

    如果你有一个仓库您的财产package.json指向一个公开的 GitHub 仓库，vsce将会自动检测并相应地调整相对链接，使用主要分支默认。你可以通过以下方式覆盖这个设置--github分支运行时标志vsce 包或vsce 发布您还可以为链接和图像设置基础网址--基础内容网址和--基础图像网址旗帜。

  • 添加一个许可证将包含扩展许可证信息的文件放置在扩展根目录。

  • 添加一个CHANGELOG.md将文件放在你的扩展根目录，并包含你的扩展更改历史的信息。

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

  • 通过指定相应的十六进制值来设置市场页面横幅的背景颜色画廊横幅颜色物业在package.json输入：.

  • 通过指定相对路径到您的扩展中包含的至少为128x128px的PNG文件来设置图标图标物业在package.json输入：.

查看更多信息在市场展示提示.

验证出版商

您可以通过验证您的品牌或身份相关联的合格域名的所有权来成为认证出版商。一旦您的出版商被验证，市场将为您的扩展详情添加一个认证徽章。

先决条件

要成为验证出版商，出版商必须在 VS 市场上有一个或多个扩展，并且域名注册必须至少有 6 个月。请在满足这些条件后再申请验证。

在 VS Code 中验证出版商指标

要验证出版商：

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

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

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

    发布者详细信息标签位置

  4. 在详细信息标签下，已验证域部分，输入一个合格的域。

    发布者详细信息标签，提供要验证的域名

    注意：在开始输入后，会在详细信息标签页标题旁边看到一个星号（*）。这与 VS Code 中相同，表示您有未保存的更改。出于同样的原因，验证按钮目前是禁用的。

  5. 选择 保存 然后 验证.

    已保存域名以验证

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

    TXT记录验证

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

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

    验证提交

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

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

已验证的出版商管理

笔记:

  • 对出版商显示名称的任何更改将撤销已验证徽章。
  • 任何未来的使用条款或上述验证违规行为，将撤销已验证徽章。

合格的域名

符合资格的域名符合以下标准：

  • 您必须能够管理DNS配置设置并添加TXT记录。
  • 这不是一个子域名 ({subdomain}.github.io, {subdomain}.contoso.com 或类似)。
  • 它必须使用HTTPS协议。
  • 它必须能够对HEAD请求以HTTP 200状态码响应。

扩展定价标签

您可以选择在您的扩展Marketplace页面上显示价格标签，以表明它是免费或免费试用输入：.

要显示价格标签，请添加定价将您的财产package.json例如：

{
  "价格": "免费"
}

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

注意

确保使用vsce版本 >=2.10.0发布您的扩展以使价格标签正常工作。

延期担保人

您可以选择接受赞助，以便为您的用户提供支持您工作的途径。

要显示赞助商链接，请添加赞助商将您的财产package.json例如：

"赞助商": {
  "链接": "https://github.com/sponsors/nvaccess"
}
注意

确保使用vsce版本 >=2.9.1当发布您的扩展以供赞助工作时。

赞助链接将在扩展的详细信息标题中显示在Marketplace和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 中安装扩展的预发布版本，以在官方扩展发布之前定期获取最新的扩展版本。

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

要发布预发布版本，请传递--预发布旗帜到vsce 包或vsce 发布命令：

vsce 包 --预发布
vsce 发布 --预发布

我们只支持主要.次要.修订对于扩展版本，语义版本号预发布标签不被支持。版本在预发布和正式发布之间必须不同。也就是说，如果1.2.3如果作为预发布上传，下次常规发布必须上传具有不同版本，例如1.2.4完整语义版本号未来将提供支持。

VS Code 会自动将扩展更新到可用的最高版本，因此，即使用户选择了一个预发布版本，并且有更高版本的扩展发布，用户将被更新到发布的版本。因此，我们建议扩展使用主要.偶数.补丁发布版本和主要.奇数.补丁对于预发布版本。例如：0.2.*发布和0.3.*预发布。

如果扩展作者不希望他们的预发布用户更新到发布版本，我们建议在发布发布版本之前总是增加并发布一个新预发布版本，以确保预发布版本始终更高。请注意，虽然预发布用户会更新到更高的发布版本，但他们仍然可以自动更新到未来版本号高于发布版本的预发布版本。

预发布扩展在 VS Code 版本之后支持1.63.0所以所有预发布扩展都应该有engines.vscode他们的价值package.json设置为>= 1.63.0输入：.

注意

已经拥有独立的预发布扩展的扩展应该联系 VS Code 团队，以启用自动卸载过时的独立扩展并安装主要扩展的预发布版本。

平台特定扩展

您可以为 VS Code 运行的每个平台（Windows、Linux、macOS）发布您的扩展的 VSIX 包。我们称这样的扩展为 平台特定的。

从版本开始1.61.0VS Code 寻找与当前平台匹配的扩展包。

平台特定的扩展在你的扩展有平台特定的库或依赖项时非常有用，这样你就可以控制平台包中包含的确切二进制文件。一个常见的用例是使用原生的 node 模块。

平台特定的扩展作为包含平台特定内容的单独包发布。您可以通过传递来指定目标平台--目标 flag。如果你不传递这个标志，该包将作为所有没有特定平台包的平台的备用包。

当前可用的平台有：win32-x64，win32-arm64，linux-x64，linux-arm64，linux-armhf，alpine-x64，alpine-arm64，达尔文-x64，达尔文-arm64和网页输入：.

如果您希望一个特定平台的扩展程序也能支持在浏览器中作为网络扩展运行，那么它必须针对网页平台发布时。网页平台尊重浏览器入口点在package.json. 禁用在该版本中不受支持的扩展功能网页我们建议使用当条款在package.json而不是单独传输package.json用于网络平台或移除在该网络平台上无法运行的 VSIX 部分网页输入：.

发布

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

以下是您如何发布VSIX的方法win32-x64和win32-arm64平台：

vsce 发布 --目标 win32-x64 win32-arm64

或者，您也可以使用--目标在打包时使用标志以创建特定于平台的 VSIX。例如，打包一个 VSIX 用于win32-x64平台并发布它：

vsce 包 --目标 win32-x64
vsce 发布 --包路径 PATH_TO_WIN32X64_VSIX

持续集成

管理多个特定平台的VSIX可能会变得令人难以应对，因此我们建议使用持续集成 (CI)工具自动化您的扩展构建过程。例如，您可以使用GitHub Actions来构建您的扩展。我们的特定平台扩展示例可以作为学习的起点：其工作流程使使用特定平台的扩展支持来跨所有支持的VS Code目标分发原生节点模块作为依赖项的常见场景成为可能。

下一步

  • 扩展市场 - 了解更多关于 VS Code 公共扩展市场的信息。
  • 测试扩展 - 为您的扩展项目添加测试以确保高质量。
  • 捆绑扩展 - 通过将你的扩展文件与webpack捆绑来提高加载时间。

常见问题

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

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

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

在创建 PAT (Personal Access Token) 时，一个简单的错误是选择一个特定的组织而不是所有可访问的组织在组织字段下拉菜单中。另一个可能的错误是范围不正确 - 您应该将授权范围设置为市场 (管理)为了发布工作。

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

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

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

请注意，当从 Windows 构建和发布您的扩展时，扩展包中的所有文件将缺少 POSIX 文件属性，即可执行位。节点模块依赖项依赖于这些属性以正常运行。从 Linux 和 macOS 发布按预期工作。

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

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

当我尝试发布我的扩展时，我得到了“错误：扩展‘name’已经在市场中存在”的错误？

市场要求扩展名称 对于每个扩展必须是唯一的。如果市场中已经存在同名的扩展，您将收到以下错误：

错误：扩展名“name”已经在市场中存在。

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

支持哪些包管理器？

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

我需要帮助处理我的 VS 市场账户或发布扩展的支持吗？

您可以通过登录 管理出版商和扩展 并点击右上角的‘联系微软’链接来联系 VS 市场支持团队。