发布插件

vsce —— 发布工具参阅

vsce是一个用于将插件发布到市场上的命令行工具。

安装

请确认本机已经安装了Node.js，然后运行：

npm install -g vsce

使用

然后你就可以在命令行里直接使用vsce了。下面是一个快速发布的示例（在你登录和打包好插件之后）:

$ vsce publish
Publishing uuid@0.0.1...
Successfully published uuid@0.0.1!

更多可用的命令参数，请使用vsce --help

发布教程

!> 注意： 出于安全考虑，vsce不会发布包含用户提供 SVG 图片的插件。

发布工具会检查以下内容：

• pacakge.json文件中的 icon 不可以是 SVG。
• pacakge.json中的徽章不可以是 SVG，除非来自于可靠的图标来源
• README.md和CHANGELOG.md中的图片链接需要使用https协议
• README.md和CHANGELOG.md中的图片不可以是 SVG，除非来自可靠的图标来源

VS Code 插件市场的服务是Visual Studio Team Services提供的，因此验证、代理、管理插件都是由这个服务提供的。

vsce只能用Personal Access Tokens发布插件，所以至少要创建一个 Token 以便发布插件。

获取 Personal Access Token

首先，你得有一个Azure DevOps 组织。

下面的例子里，我们假设组织名为vscode，从你的组织主页（例如：https://dev.azure.com/vscode ）进入安全（Security）页面：

选择 Personal Access Token，点击New Token创建一个新的 Personal Access Token

给 Personal Access Token 添加描述，过期时间等等，你最好把过期时间设置为 1 年，这样你接下就能方便很多，选择custom defined（用户自定义）范围，然后点击Show all scopes(显示全部)

最后，在这个列表中找到Marketplace，并勾选Acquire和Manage

点击Create，你就会看到新创建的 Personal Access Token 了，复制好，你接下来就会用到这个 token 来创建一个发行方了。

创建一个发行方

发行方是 VS Code 市场有权发布插件的唯一标识，每个插件的package.json文件都包含着publisher字段。

现在我们已经有了Personal Access Token，我们马上可以用vsce创建一个发行方：

vsce create-publisher (publisher name)

vsce会记住这个 Personal Access Token，日后你需要再次使用的时候会自动带上。

?> 注意：另外，你也可以在市场的发行方管理页中创建发行方，然后用这个账号登录vsce。

发行方登录

如果你已经有发行方账号了：

vsce login (publisher name)

和create-publisher命令类似地，vsce会要求输入你的 Personal Access Token。

你也可以用命令参数-p <token>直接登录然后立即发布插件：

vsce publish -p <token>

增量更新插件版本

用 SemVer 语义标识符：major，minor，patch增量更新插件版本号。

例如，你想把插件从 1.0.0 更新到 1.1.0，那么加上minor：

vsce publish minor

插件package.json的 version 会先更新，然后才发布插件。

你也可以通过命令行指定版本号：

vsce publish 2.0.1

下架插件

通过指定插件 idpublisher.extension下架插件：

vsce unpublish (publisher name).(extension name)

!> 注意：当你下架插件的时候，市场会移除所有插件的历史统计数据，请在下架前再三考虑，最好还是更新插件吧。

插件打包

你也可能只是想打包一下插件，而不是发布到商店里。用下列命令将插件打包到.vsix文件中：

vsce package

这个命令会在当前目录生成一个.vsix文件，直接从.vsix安装插件是允许的，查看从 VSIX 安装插件了解更多内容。

VS Code 版本兼容性

当你制作插件的时候，你需要描述插件对 VS Code 的版本兼容性——修改package.json中的engines.vscode：

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

1.8.0表示你的插件只能兼容1.8.0版本的 VS Code，^1.8.0则表示你的插件向上兼容，包括1.8.1, 1.9.0等等。

使用engines.vscode可以确保插件安装环境包含了插件依赖的 API。这个机制在稳定版和 Insider 版本都适用。

现在我们假设最新的稳定版 API 是1.8.0，而1.9.0引入了新的 API，所以你可以用1.9.0-insider标识插件在 Insider 版中也可正常使用。 如果你想使用这些刚刚引入的 API，则将依赖版本设置为^1.9.0，你的插件则只能安装在>=1.9.0的 VS Code 上，也就意味着所有当前的 Insider 版本都可以用得上，而稳定版只有在更新到1.9.0才能使用你的插件。

进阶用法

符合市场的插件

你可以自定义插件在市场中的外观，查看示例GO 插件。

下面是一些让你的插件在市场看起来更酷的小提示：

• 插件根目录下面的README.md文件可以用来填充插件市场的页面内容。vsce会将 README 中的链接通过下面两种方式修改掉：
  • 如果你的package.json的repository字段是一个 Github 仓库，vsce会自动检测，然后相应地调整链接。
  • 运行vsce package时，加上--baseContentUrl和--baseImagesUrl标识重载上述行为。
• 插件根目录下的LICENSE会成为插件的 license。
• 同样的CHANGELOG.md文件会成为插件的发布日志。
• 通过设置package.json的galleryBanner.colorhex 值，修改 banner 的背景色。

• 通过给package.json中的icon设置一个相对路径，可以将一个128px的 PNG 图标放进你的插件中。

• 参见插件市场展现小提示

.vscodeignore

创建一个.vscodeignore文件可以排除插件目录中的内容。这个文件支持glob模式，每个表达式一行。

例如：

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

你应该忽略哪些不必在运行时用到的文件。例如：你的插件是用 Typescript 写的，那么你就应该忽略所有的**/*.ts文件。

?> 注意：在devDependencies列出的开发依赖会被自动忽略，你不必将他们加入到.vscodeignore中。

预发布步骤

你是可以在清单文件中添加预发布步骤的，下面的命令会在插件每次打包时执行：

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

上面的示例会在每次插件打包时调用 Typescript 编译器。

FAQ

问：当我发布插件时遇到了 403 Forbidden（或 401 Unauthorized）错误？

答：很有可能是你创建 PAT (Personal Access Token) 时没有选择all accessible accounts。你还需要将授权范围设置为All scopes，这样发布工具才能工作。

问：我没办法用vsce工具下架插件？

答：你可能改变了插件 ID 或者发行方名称。不过你还可以在管理页面发布或者下架插件。

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

答：请注意，当你在 Windows 平台构建和发布插件的时候，所有插件包内的文件会丢失 POSIX 文件属性，或称之为执行位（executable bit）的东西。一些基于这些属性的node_modules依赖则会调整工作方式。从 Linux 和 macOS 平台构建则会如预期执行。

下一步

• 插件市场 - 学习更多 VS Code 公共插件市场。
• 测试插件 - 添加插件测试，提高插件质量。