felipecrs/semantic-release-vsce
GitHub: felipecrs/semantic-release-vsce
这是一个 semantic-release 插件，用于自动化 VS Code 扩展的打包和发布到官方市场。
Stars: 41 | Forks: 16
# 语义发布VS Code扩展插件
[语义发布](https://github.com/semantic-release/semantic-release)插件，用于打包和发布VS Code扩展。
[](https://www.npmjs.com/package/semantic-release-vsce)
[](https://www.npmjs.com/package/semantic-release-vsce)
[](https://github.com/felipecrs/semantic-release-vsce/actions?query=workflow%3Aci)
[](https://david-dm.org/felipecrs/semantic-release-vsce)
[](https://david-dm.org/felipecrs/semantic-release-vsce?type=peer)
[](https://github.com/semantic-release/semantic-release)
| 步骤 | 描述 |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify` | 当启用发布时，验证`package.json`以及针对Visual Studio Marketplace和/或Open VSX Registry的个人访问令牌的有效性。 |
| `prepare` | 使用`vsce`生成`.vsix`文件（可通过 [`packageVsix` 配置选项](#packagevsix) 控制） |
| `publish` | 将扩展发布到Visual Studio Marketplace和/或Open VSX Registry（在此处了解更多[此处](#publishing)） |
## 安装
```
npm install --save-dev semantic-release-vsce
```
或
```
yarn add --dev semantic-release-vsce
```
## 用法
该插件可以在 [**语义发布** 配置文件](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration)中进行配置：
```
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-vsce",
{
"packageVsix": true
}
],
[
"@semantic-release/github",
{
"assets": [
{
"path": "*.vsix"
}
]
}
]
]
}
```
## 配置
### `打包 VSIX`
是否将扩展打包成`.vsix`文件，或将其放置在何处。这控制是否调用`vsce package`命令，以及为`vsce package --out`使用什么值。
| 值 | 描述 |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `"auto"` (默认) | 当[`publish`](#publish)被禁用或存在`OVSX_PAT`环境变量时，行为等同于`true` |
| `true` | 将扩展打包为`.vsix`文件，并将其放置在当前工作目录 |
| `false` | 完全禁用打包扩展的`.vsix`文件 |
| 一个 `string` 字符串 | 将扩展打包为`.vsix`文件，并将其放置在指定路径 |
### `发布`
是否将扩展发布到Visual Studio Marketplace和/或Open VSX Registry。这控制是否调用`vsce publish`或`ovsx publish`命令。在此处了解更多[此处](#publishing)。
| 值 | 描述 |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `true` (默认) | 将扩展发布到Visual Studio Marketplace和/或Open VSX Registry |
| `false` | 禁用将扩展发布到Visual Studio Marketplace和/或Open VSX Registry |
### `发布包路径`
要发布的`.vsix`文件（或文件列表）。这控制为`vsce publish --packagePath`使用什么值。
| 值 | 描述 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `"auto"` (默认) | 使用在`prepare`步骤中打包的`.vsix`文件（如果已打包），否则行为等同于`false` |
| `false` | 不使用`.vsix`文件发布，这会导致`vsce`在发布过程中打包扩展 |
| 一个 `string` 字符串 | 发布指定的`.vsix`文件。这可以是glob模式，或用逗号分隔的文件列表 |
### `包根目录`
扩展目录相对于当前工作目录的路径。默认为`cwd`。
### 环境变量
此插件支持以下环境变量：
| 变量 | 描述 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OVSX_PAT` | _可选_。用于推送到Open VSX Registry的个人访问令牌。 |
| `VSCE_PAT` | _可选_。用于发布到Visual Studio Marketplace的个人访问令牌。 _注意:_ 不能与`VSCE_AZURE_CREDENTIAL`同时设置。 |
| `VSCE_AZURE_CREDENTIAL` | _可选_。当设置为`true`或`1`时，`vsce`将使用`--azure-credential`标志进行身份验证。 _注意:_ 不能与`VSCE_PAT`同时设置。 |
| `VSCE_PRE_RELEASE` | _可选_。当设置为`true`或`1`时，`vsce`在打包扩展时将使用`--pre-release`标志将其标记为预发布版本。 |
| `VSCE_TARGET` | _可选_。打包或发布扩展时要使用的目标平台（用作`vsce package --target ${VSCE_TARGET}`）。当设置为`universal`时，行为等同于未设置`VSCE_TARGET`（即构建通用/跨平台的`vsix`）。参见[平台特定示例](#platform-specific-on-github-actions) |
### 配置 `vsce`
您可以在`package.json`中设置`vsce`选项，例如：
```
{
"vsce": {
"baseImagesUrl": "https://my.custom/base/images/url",
"dependencies": true,
"yarn": false
}
}
```
更多信息，请查看 [`vsce` 文档](https://github.com/microsoft/vscode-vsce#configuration)。
## 发布
此插件可以将扩展发布到Visual Studio Marketplace和/或Open VSX Registry。
您可以使用 [`publish`](#publish) 配置选项来启用或禁用发布。
当发布被启用时（默认），如果存在`VSCE_PAT`环境变量，插件将发布到Visual Studio Marketplace，如果存在`OVSX_PAT`环境变量，则和/或发布到Open VSX Registry。
例如，如果您只想将`.vsix`文件作为GitHub发布资产发布，您可能希望禁用发布。
### 发布到 Visual Studio Marketplace
使用此插件将扩展发布到Visual Studio Marketplace很简单：
1. 为Visual Studio Marketplace创建您的个人访问令牌。在此处了解更多[此处](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token)。
2. 在您的CI中配置`VSCE_PAT`环境变量，使用您创建的令牌。
3. 大功告成！插件将自动检测环境变量并发布到Visual Studio Marketplace，无需额外配置。
### 发布到 Open VSX Registry
使用此插件将扩展发布到Open VSX Registry很简单：
1. 为Open VSX Registry创建您的个人访问令牌。在此处了解更多[此处](https://github.com/eclipse/openvsx/wiki)。
2. 在您的CI中配置`OVSX_PAT`环境变量，使用您创建的令牌。
3. 大功告成！插件将自动检测环境变量并发布到Open VSX Registry，无需额外配置。
## 示例
### GitHub Actions
```
name: release
on:
push:
branches:
- master
permissions:
contents: read # for checkout
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# In case you want to publish to Visual Studio Marketplace
VSCE_PAT: ${{ secrets.VSCE_PAT }}
# In case you want to publish to Open VSX Registry
OVSX_PAT: ${{ secrets.OVSX_PAT }}
```
### GitHub Actions 中的平台特定发布
1. 安装 [`semantic-release-stop-before-publish`](https://github.com/felipecrs/semantic-release-stop-before-publish)
npm install --save-dev semantic-release-stop-before-publish
我们将用它让`semantic-release`在发布任何内容之前停止，以便我们可以在矩阵中使用`semantic-release`来构建每个`.vsix`。
2. 将您的`semantic-release`配置分为两个，一个用于打包，另一个用于发布。
用于打包的配置包含`semantic-release-stop-before-publish`，以便`semantic-release`不发布任何内容（包括git标签）。
// package.release.config.js
/**
* @type {import('semantic-release').GlobalConfig}
*/
export default {
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
[
'semantic-release-vsce',
{
packageVsix: true,
publish: false,
},
],
'semantic-release-stop-before-publish',
],
};
用于发布的配置不打包`.vsix`，但会发布所有`*.vsix`文件。
// publish.release.config.js
/**
* @type {import('semantic-release').GlobalConfig}
*/
export default {
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
[
'semantic-release-vsce',
{
packageVsix: false,
publishPackagePath: '*.vsix',
},
],
[
'@semantic-release/github',
{
assets: '*.vsix',
},
],
],
};
3. 创建类似下面的工作流文件：
```
# .github/workflows/ci.yaml 的 CI 配置文件路径
name: ci
on:
push:
branches:
- master
permissions:
contents: read # for checkout
jobs:
build:
strategy:
matrix:
include:
- os: windows-latest
target: win32-x64
npm_config_arch: x64
- os: windows-latest
target: win32-arm64
npm_config_arch: arm64
- os: ubuntu-latest
target: linux-x64
npm_config_arch: x64
- os: ubuntu-latest
target: linux-arm64
npm_config_arch: arm64
- os: ubuntu-latest
target: linux-armhf
npm_config_arch: arm
- os: ubuntu-latest
target: alpine-x64
npm_config_arch: x64
- os: ubuntu-latest
target: alpine-arm64
npm_config_arch: arm64
- os: macos-latest
target: darwin-x64
npm_config_arch: x64
- os: macos-latest
target: darwin-arm64
npm_config_arch: arm64
- os: ubuntu-latest
target: universal
runs-on: ${{ matrix.os }}
# Even though semantic-release will not publish anything, it still needs to
# validate the GITHUB_TOKEN
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- if: matrix.target != 'universal'
name: Install dependencies (with binaries)
run: npm ci
env:
npm_config_arch: ${{ matrix.npm_config_arch }}
- if: matrix.target == 'universal'
name: Install dependencies (without binaries)
run: npm ci
- run: npx semantic-release --extends ./package.release.config.js
env:
VSCE_TARGET: ${{ matrix.target }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- uses: actions/upload-artifact@v4
with:
name: ${{ matrix.target }}
path: '*.vsix'
# vsce updates the version in package.json and package-lock.json during
# package step, so we need to save them for the publish step
- if: matrix.target == 'universal'
uses: actions/upload-artifact@v4
with:
name: package-json
path: |
package.json
package-lock.json
release:
runs-on: ubuntu-latest
needs: build
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
with:
merge-multiple: true
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- run: npx semantic-release --extends ./publish.release.config.js
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# In case you want to publish to Visual Studio Marketplace
VSCE_PAT: ${{ secrets.VSCE_PAT }}
# In case you want to publish to Open VSX Registry
OVSX_PAT: ${{ secrets.OVSX_PAT }}
```
### GitHub Actions - 使用Azure凭据发布到VS Marketplace
```
name: release
on:
push:
branches:
- master
permissions:
contents: read # for checkout
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # to be able to publish a GitHub release
issues: write # to be able to comment on released issues
pull-requests: write # to be able to comment on released pull requests
steps:
- uses: actions/checkout@v4
- uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm audit signatures
- run: npx semantic-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
VSCE_AZURE_CREDENTIAL: 'true'
```
在 [VS Code ShellCheck 扩展](https://github.com/vscode-shellcheck/vscode-shellcheck/pull/805)中也可以找到参考实现。
标签：GNU通用公共许可证, MITM代理, Node.js, npm, Open VSX Registry, semantic-release插件, Visual Studio Marketplace, vsce, VS Code扩展, 二进制发布, 发布工具, 开源工具, 打包工具, 扩展市场, 插件管理, 暗色界面, 版本管理, 自动化发布, 自定义脚本, 软件开发