发布扩展
一旦你制作了一个高质量的扩展,你可以将其发布到 VS Code 扩展市场,以便其他人可以找到、下载和使用你的扩展。或者,你可以将扩展打包成可安装的 VSIX 格式,并与其他用户共享。
本主题涵盖
vsce
vsce,是 "Visual Studio Code Extensions" 的缩写,是一个用于打包、发布和管理 VS Code 扩展的命令行工具。
安装
确保你已安装 Node.js。然后运行
npm install -g @vscode/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
,你应该根据需要使用你的新组织名称。请注意,组织名称不一定与你的发布者名称相同。
-
从你的组织主页(例如:
https://dev.azure.com/vscode
)中,打开你的个人资料图像旁边的用户设置下拉菜单,然后选择 个人访问令牌 -
在 个人访问令牌 页面上,选择 新建令牌
-
在创建新的个人访问令牌模式窗口中,为令牌选择以下详细信息
- 名称:你想要为令牌设置的任何名称
- 组织:所有可访问的组织
- 过期时间(可选):设置令牌的所需过期日期
- 作用域:自定义定义
- 单击 作用域 部分下方的 显示所有作用域 链接
- 在作用域列表中,滚动到 市场 并选择 管理 作用域
-
单击 创建。
你将看到新创建的个人访问令牌。复制 它到安全位置,你将需要它来创建发布者。
创建发布者
发布者 是一个身份,可以将扩展发布到 Visual Studio Code 市场。每个扩展都需要在其package.json
文件中包含一个 publisher
标识符。
要创建发布者
-
使用你用于在上一节中创建个人访问令牌的同一 Microsoft 帐户登录。
-
单击左侧窗格中的 创建发布者。
-
在新页面中,为新发布者指定强制性参数 - 标识符和名称(分别为 ID 和 名称 字段)
- ID:你的发布者在市场中的 唯一 标识符,将在你的扩展 URL 中使用。ID 一旦创建就无法更改。
- 名称:你的发布者的 唯一 名称,将与你的扩展一起显示在市场中。这可以是你的公司或品牌名称。
以下是 Docker 扩展的发布者标识符和名称的示例
-
可选择填写其余字段。
-
单击 创建
-
使用
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>'.
验证后,你就可以发布扩展了。
发布扩展
你可以通过两种方式发布扩展
-
自动,使用
vsce publish
命令vsce publish
如果你尚未通过上面的
vsce login
命令提供你的个人访问令牌,vsce
将会询问你。 -
手动,使用
vsce package
将扩展打包成可安装的 VSIX 格式,然后将其上传到Visual Studio Marketplace 发布者管理页面
查看扩展安装和评分
Visual Studio Marketplace 发布者管理页面 使你可以访问每个扩展随时间推移的获取趋势,以及总获取计数和评分与评论。要查看报告,请单击扩展或选择 更多操作 > 报告。
自动递增扩展版本
发布扩展时,你可以通过指定要递增的SemVer 兼容数字或版本(major
、minor
或 patch
)来自动递增其版本号。例如,要将扩展的版本从 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
和unpublish
命令vsce unpublish <publisher id>.<extension name>
-
手动,从Visual Studio Marketplace 发布者管理页面中,单击 更多操作 > 移除
在这两种情况下,系统都会提示你通过键入扩展名称来确认移除。请注意,移除操作是 不可逆的。
当你移除扩展时,市场也会移除任何扩展统计信息。你可能想要取消发布你的扩展,而不是移除它。
弃用扩展
你可以仅弃用扩展,或弃用以支持另一个扩展或设置。弃用的扩展将在 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 中的扩展视图
- 转到扩展视图。
- 选择 视图和更多操作...
- 选择 从 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 Code1.8.0
兼容。 - 值
^1.8.0
表示你的扩展与 VS Code1.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
版本在 Insider 版本中提供。如果你想发布一个受益于此 API 的扩展版本,你应该指示版本依赖项为 ^1.9.0
。这样,你的新扩展版本将仅在 VS Code >=1.9.0
上可用(换句话说,使用当前 Insiders 版本的用户)。VS Code 稳定版的用户只有在稳定版达到 1.9.0
版本时才会获得更新。
高级用法
市场集成
你可以自定义你的扩展在 Visual Studio Marketplace 中的外观。有关示例,请参阅Go 扩展。
以下是一些使你的扩展在市场上看起来很棒的技巧
-
在你的扩展的根目录中添加一个
README.md
文件,其中包含你想要在扩展的市场页面上显示的内容。注意如果你的
package.json
中有一个指向公共 GitHub 存储库的repository
属性,则vsce
将自动检测到它并相应地调整相对链接,默认情况下使用main
分支。你可以在运行vsce package
或vsce publish
时使用--githubBranch
标志覆盖此设置。你还可以使用--baseContentUrl
和--baseImagesUrl
标志设置链接和图像的基本 URL。 -
在你的扩展的根目录中添加一个
LICENSE
文件,其中包含有关扩展许可证的信息。 -
在你的扩展的根目录中添加一个
CHANGELOG.md
文件,其中包含有关你的扩展的更改历史记录的信息。 -
在你的扩展的根目录中添加一个
SUPPORT.md
文件,其中包含有关如何获得扩展支持的信息。 -
通过在
package.json
中指定相应的十六进制值(通过galleryBanner.color
属性)来设置市场页面上的横幅背景颜色。 -
通过在
package.json
中指定一个指向你的扩展中包含的 128x128px PNG 文件的相对路径(通过icon
属性)来设置图标。
有关更多信息,请参阅市场展示技巧。
验证发布者
你可以通过验证与你的品牌或身份关联的符合条件的域的所有权来成为 已验证的发布者。一旦你的发布者经过验证,市场将在你的扩展详细信息中添加一个已验证徽章。
先决条件
要获得验证,发布者必须在 VS Marketplace 上至少有一个或多个扩展发布了 6 个月,并且域的注册也必须至少有 6 个月。请等到满足这些条件后再申请验证。
要验证发布者
-
在左侧窗格中,选择或创建一个你想要验证的发布者。
-
在主窗格中,选择 详细信息 选项卡。
-
在 详细信息选项卡 中,在 已验证域 部分下,键入一个符合条件的域。
注意:在你开始键入后,请注意 详细信息 选项卡标题旁边的星号 (*)。就像在 VS Code 中一样,这表示你有未保存的更改。出于同样的原因,验证 按钮仍然处于禁用状态。
-
选择 保存,然后选择 验证。
将出现一个对话窗口,为你提供有关向你的域的 DNS 配置添加 TXT 记录的说明。
-
按照说明将 TXT 记录添加到你的域的 DNS 配置。
-
在对话窗口中选择 验证,以验证 TXT 记录是否已成功添加。
一旦你的 TXT 记录经过验证,市场团队将审核你的请求,并在 5 个工作日内告知你结果。验证包括但不限于:域、网站和扩展跟踪记录的先决条件、内容资格、合法性、信任和良好声誉。
如果验证通过,你将在 Visual Studio Marketplace 发布者管理页面中的发布者名称旁边看到相应的徽章
注意:
- 对发布者显示名称的任何更改都将撤销已验证的徽章。
- 发布者未来发生的任何使用条款或上述验证违规行为都将撤销已验证的徽章。
符合条件的域
符合条件的域满足以下条件
- 你必须能够管理 DNS 配置设置并添加 TXT 记录。
- 它不是子域 ({subdomain}.github.io、{subdomain}.contoso.com 或类似域名)。
- 它必须使用 HTTPS 协议。
- 它必须能够对 HEAD 请求响应 HTTP 200 状态。
扩展定价标签
你可以选择在你的扩展的市场页面上显示定价标签,以表明它是 Free
或 Free Trial
。
要显示定价标签,请将 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
发布你的扩展时,赞助才能正常工作。
赞助商链接将显示在你的扩展在市场和 VS Code 中的页面中的扩展详细信息标头中
我们希望这将允许我们的用户资助他们依赖的扩展,以提高扩展的性能、可靠性和稳定性。
使用 .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 中安装扩展的预发布版本,以便在正式扩展发布之前定期获取最新的扩展版本。
要发布预发布版本,请将 --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 会查找与当前平台匹配的扩展包。
如果你的扩展具有平台特定的库或依赖项,则平台特定扩展非常有用,因此你可以控制平台包中包含的确切二进制文件。一个常见的用例是使用 本机 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 构建你的扩展。我们的 平台特定扩展示例 可用作学习的起点:它的 workflow 启用了使用平台特定扩展支持跨所有受支持的 VS Code 目标分发本机 node 模块作为依赖项的常见场景。
后续步骤
常见问题
当我尝试发布我的扩展时,收到 "You exceeded the number of allowed tags of 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 以自动将你的扩展发布到 Marketplace。
当我尝试发布我的扩展时,收到“ERROR 扩展 'name' 在 Marketplace 中已存在”错误,该怎么办?
Marketplace 要求每个扩展的 扩展名称 都是唯一的。如果 Marketplace 中已存在同名的扩展,你将收到以下错误
ERROR The extension 'name' already exists in the Marketplace.
同样的规则适用于扩展的 显示名称。
支持哪些软件包管理器?
你可以使用 npm 或 yarn v1 来管理你的扩展依赖项。
我在 VS Marketplace 帐户方面需要帮助,或者在发布扩展方面需要支持,该怎么办?
你可以通过登录到 管理发布者和扩展 并点击右上角的“联系 Microsoft”链接来联系 VS Marketplace 支持团队。