semantic-release-vsce

semantic-release 插件，用于打包和发布 VS Code 扩展。

步骤	描述
`verify`	当启用发布时，验证 `package.json` 以及个人访问令牌在 Visual Studio Marketplace 和/或 Open VSX Registry 上的有效性
`prepare`	使用 `vsce` 生成 `.vsix` 文件（可通过 `packageVsix` 配置选项控制
`publish`	将扩展发布到 Visual Studio Marketplace 和/或 Open VSX Registry（了解更多请参见此处)

安装

npm install --save-dev semantic-release-vsce

或

yarn add --dev semantic-release-vsce

用法

该插件可在 semantic-release 配置文件中进行配置：

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-vsce",
      {
        "packageVsix": true
      }
    ],
    [
      "@semantic-release/github",
      {
        "assets": [
          {
            "path": "*.vsix"
          }
        ]
      }
    ]
  ]
}

配置

`packageVsix`

是否将扩展打包为 .vsix 文件，或将其放置在何处。这控制是否调用 vsce package，以及 vsce package --out 将使用什么值。

值	描述
`"auto"` (默认)	如果 `publish` 已禁用或存在 `OVSX_PAT` 环境变量，则行为与 `true` 相同
`true`	将扩展打包为 `.vsix`，并将其放置在当前工作目录
`false`	完全禁用扩展的打包 `.vsix`
一个 `string`	将扩展打包为 `.vsix` 并将其放置在指定路径

`publish`

是否将扩展发布到 Visual Studio Marketplace 和/或 Open VSX Registry。这控制是否调用 vsce publish 或 ovsx publish。了解更多 here。

Value	Description
`true` (default)	将扩展发布到 Visual Studio Marketplace 和/或 Open VSX Registry
`false`	禁用将扩展发布到 Visual Studio Marketplace 和/或 Open VSX Registry

`publishPackagePath`

要发布哪个 .vsix 文件（或文件）。这控制将使用哪个值作为 vsce publish --packagePath。

值	描述
`"auto"` (默认)	使用在 `prepare` 步骤中打包的 `.vsix`（如果已打包），否则行为如同 `false`
`false`	不使用 `.vsix` 文件进行发布，这会导致 `vsce` 在发布过程中将扩展作为一部分进行打包
一个 `string`	发布指定的 `.vsix` 文件。这可以是一个 glob 模式，或一个逗号分隔的文件列表

`packageRoot`

扩展相对于当前工作目录的目录。默认为 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`）。参见平台特定示例

配置 `vsce`

您可以在 package.json 中设置 vsce 选项，例如：

{
  "vsce": {
    "baseImagesUrl": "https://my.custom/base/images/url",
    "dependencies": true,
    "yarn": false
  }
}

有关更多信息，请查阅 vsce 文档。

发布

此插件可以将扩展发布到 Visual Studio Marketplace 和/或 Open VSX Registry。

您可以通过 publish 配置选项启用或禁用发布。

当发布功能启用时（默认），如果存在 VSCE_PAT 环境变量，插件将发布到 Visual Studio Marketplace，和/或如果存在 OVSX_PAT 环境变量，则发布到 Open VSX Registry。

例如，如果您只想将 .vsix 文件作为 GitHub 发布资产发布，您可能希望禁用发布功能。

发布到 Visual Studio Marketplace

使用此插件将扩展发布到 Visual Studio Marketplace 非常简单：

为您的 Visual Studio Marketplace 创建个人访问令牌。了解更多请参见此处。
在您的 CI 中配置 VSCE_PAT 环境变量，使用您创建的令牌。
享受吧！插件将自动检测环境变量并将其发布到 Visual Studio Marketplace，无需额外配置。

发布到 Open VSX Registry

使用此插件将扩展发布到 Open VSX Registry 非常简单：

为您的 Open VSX Registry 创建个人访问令牌。了解更多请参见此处。
在您的 CI 中配置 OVSX_PAT 环境变量，使用您创建的令牌。
享受吧！插件将自动检测环境变量并将其发布到 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 上的平台特定配置

安装 semantic-release-stop-before-publish

npm install --save-dev semantic-release-stop-before-publish

我们将使用它来让 semantic-release 在发布任何内容之前停止，以便我们可以使用 semantic-release 在矩阵中构建每个 .vsix。

将您的 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',
      },
    ],
  ],
};

注意： 别忘了移除现有的 semantic-release 配置。

创建一个如下所示的工作流文件：

# .github/workflows/ci.yaml
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 扩展中找到。