# 发布插件

# vsce —— 发布工具参阅

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

# 安装


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

npm install -g vsce
1

# 使用


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

$ vsce publish
Publishing uuid@0.0.1...
Successfully published uuid@0.0.1!
1
2
3

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

# 发布教程


注意

出于安全考虑,vsce不会发布包含用户提供 SVG 图片的插件。

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

  • pacakge.json文件中的 icon 不可以是 SVG。
  • pacakge.json中的徽章不可以是 SVG,除非来自于可靠的图标来源
  • README.mdCHANGELOG.md中的图片链接需要使用https协议
  • README.mdCHANGELOG.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)**页面:

publishers1

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

publishers2

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

publishers3

最后,在这个列表中找到Marketplace,并勾选AcquireManage

publishers4

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

# 创建一个发行方

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

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

vsce create-publisher (publisher name)
1

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

WARNING

另外,你也可以在市场的发行方管理页中创建发行方,然后用这个账号登录vsce

# 发行方登录

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

vsce login (publisher name)
1

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

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

vsce publish -p <token>
1

# 增量更新插件版本

用 SemVer 语义标识符:majorminorpatch增量更新插件版本号。

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

vsce publish minor
1

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

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

vsce publish 2.0.1
1

# 下架插件

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

vsce unpublish (publisher name).(extension name)
1

注意

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

# 插件打包

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

vsce package
1

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

# VS Code 版本兼容性

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

{
  "engines": {
    "vscode": "^1.8.0"
  }
}
1
2
3
4
5

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.jsonrepository字段是一个 Github 仓库,vsce会自动检测,然后相应地调整链接。
    • 运行vsce package时,加上--baseContentUrl--baseImagesUrl标识重载上述行为。
  • 插件根目录下的LICENSE会成为插件的 license。

  • 同样的CHANGELOG.md文件会成为插件的发布日志。

  • 通过设置package.jsongalleryBanner.colorhex 值,修改 banner 的背景色。

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

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

# .vscodeignore

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

例如:

**/*.ts
**/tsconfig.json
!file.ts
1
2
3

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

WARNING

devDependencies列出的开发依赖会被自动忽略,你不必将他们加入到.vscodeignore中。

# 预发布步骤

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

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "joaomoreno",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}
1
2
3
4
5
6
7
8
9
10
11

上面的示例会在每次插件打包时调用 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 平台构建则会如预期执行。

# 下一步