全栈攻城狮

Appearance

实战：插件发布全流程 ​

前面几篇文章拆解了打包、发布、元数据、版本、安全与商业化的各个侧面，本文把它们串成一条可执行的发布链路。以示例插件 my-extension（代码格式化工具）为例，从零走到 GitHub Actions 自动发布。

项目准备 ​

发布前确认项目已具备基本结构：

text
my-extension/
 ├── src/
 │    └── extension.ts
 ├── images/
 │    └── icon.png
 ├── package.json
 ├── tsconfig.json
 ├── README.md
 ├── CHANGELOG.md
 ├── LICENSE
 └── .vscodeignore

核心代码已实现并本地调试通过。

第一步：完善 package.json 元数据 ​

补齐发布必需的全部字段：

json
{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "一键格式化并实时预览代码，支持 20 种语言",
  "version": "1.0.0",
  "publisher": "mypublisher",
  "author": "Zhang San <zhangsan@example.com>",
  "license": "MIT",
  "icon": "images/icon.png",
  "galleryBanner": {
    "color": "#1e1e2e",
    "theme": "dark"
  },
  "homepage": "https://github.com/zhangsan/my-extension",
  "repository": {
    "type": "git",
    "url": "https://github.com/zhangsan/my-extension"
  },
  "bugs": {
    "url": "https://github.com/zhangsan/my-extension/issues"
  },
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": ["Formatters"],
  "keywords": ["format", "beautify", "prettify", "pretty", "json"],
  "main": "./dist/extension.js",
  "activationEvents": ["onCommand:myext.format"],
  "contributes": {
    "commands": [
      {
        "command": "myext.format",
        "title": "My Extension: 格式化代码"
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "node esbuild.js",
    "watch": "node esbuild.js --watch",
    "package": "vsce package"
  },
  "devDependencies": {
    "@types/vscode": "^1.85.0",
    "esbuild": "^0.19.0",
    "typescript": "^5.3.0"
  }
}

publisher 字段先填计划创建的发布者 ID，与 Marketplace 上的 Publisher 必须一致。

第二步：配置 .vscodeignore ​

排除源码、测试、开发配置，只保留运行产物：

text
# 构建产物与源码
src/**
dist/**/*.map
test/**
tests/**
**/*.ts
**/*.map

# 依赖
node_modules/**

# 版本控制与 CI
.git/**
.github/**
.gitignore

# IDE 配置
.vscode/**
.idea/**

# 文档保留 README 与 CHANGELOG
*.md
!README.md
!CHANGELOG.md
docs/**

# 构建配置
tsconfig.json
esbuild.js
package-lock.json

第三步：本地打包验证 ​

编译 ​

bash
npm install
npm run compile

预览打包内容 ​

bash
npx @vscode/vsce ls
text
dist/
dist/extension.js
package.json
README.md
CHANGELOG.md
LICENSE
images/
images/icon.png

打包 ​

bash
npx @vscode/vsce package
text
DONE  Packaged: my-extension-1.0.0.vsix (48.3 KB)

本地安装验证 ​

bash
code --install-extension my-extension-1.0.0.vsix

启动 VS Code，执行 My Extension: 格式化代码 命令，确认功能正常，然后卸载：

bash
code --uninstall-extension mypublisher.my-extension

本地验证通过，再进行发布。

第四步：创建 Azure DevOps Publisher 与 PAT ​

创建组织与 Publisher ​

  1. 登录 dev.azure.com，创建组织（如 myvscodeext）
  2. 访问 marketplace.visualstudio.com/manage，用该组织创建 Publisher
  3. Publisher ID 设为 mypublisher，与 package.json 的 publisher 字段一致

生成 PAT ​

text
https://dev.azure.com/myvscodeext/_usersSettings/tokens

New Token → Scopes: Marketplace → Manage

勾选 Marketplace 下的 Manage 权限后生成令牌并复制。

本地登录 ​

bash
npx @vscode/vsce login mypublisher
text
Personal Access Token: ****************************************************************
The Personal Access Token verification succeeded for the publisher 'mypublisher'.

第五步：首次发布 ​

bash
npx @vscode/vsce publish

发布流程会自动执行 vscode:prepublish 编译、打包、上传：

text
DONE  Published mypublisher.my-extension@1.0.0
INFO  Open https://marketplace.visualstudio.com/items?itemName=mypublisher.my-extension

打开链接核对插件页：图标、描述、README、Changelog 标签是否完整。

第六步：编写 CHANGELOG 与版本递增 ​

维护 CHANGELOG.md ​

每次改动先更新 CHANGELOG.md，再决定版本号：

markdown
# Changelog

## [1.1.0] - 2026-04-01

### 新增

- 支持 JSON 文件实时预览
- 新增格式化历史撤销功能

### 修复

- 修复大文件格式化时编辑器卡顿的问题

## [1.0.0] - 2026-01-10

### 新增

- 首次发布：代码格式化与实时预览

按变更类型递增版本 ​

bash
# 修复 Bug：1.0.0 → 1.0.1
npx @vscode/vsce publish patch

# 新增功能：1.0.0 → 1.1.0
npx @vscode/vsce publish minor

# 破坏性变更：1.0.0 → 2.0.0
npx @vscode/vsce publish major

vsce publish patch/minor/major 会同步改写 package.json 的 version，无需手动修改。

第七步：GitHub Actions 自动打包发布 ​

手动发布容易遗漏步骤，用 GitHub Actions 在 Release 触发时自动完成打包与发布。

配置 Secrets ​

在仓库 Settings → Secrets and variables → Actions 中新增：

Secret 名称值
VSCE_PAT上文生成的 Personal Access Token

工作流文件 ​

.github/workflows/publish.yml：

yaml
name: Publish Extension

# 打 tag 或创建 Release 时触发
on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: 安装依赖
        run: npm ci

      - name: 校验版本号与 tag 一致
        run: |
          TAG_VERSION="${GITHUB_REF_NAME#v}"
          PKG_VERSION=$(node -p "require('./package.json').version")
          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
            echo "tag($TAG_VERSION) 与 package.json($PKG_VERSION) 不一致"
            exit 1
          fi

      - name: 发布到 Marketplace
        run: npx @vscode/vsce publish --pat "${{ secrets.VSCE_PAT }}"

      - name: 打包产物供 Release 附件使用
        run: npx @vscode/vsce package -o my-extension-${{ github.ref_name }}.vsix

      - name: 上传 .vsix 到 Release
        uses: softprops/action-gh-release@v2
        with:
          files: my-extension-*.vsix

发布流程的自动化闭环 ​

bash
# 1. 更新 CHANGELOG.md 与 package.json 版本号
# 2. 提交并打 tag
git add CHANGELOG.md package.json
git commit -m "chore: release 1.1.0"
git tag v1.1.0
git push origin main --tags

Push tag 后 Actions 自动执行：校验 tag 与版本一致 → vsce publish 发布到 Marketplace → 把 .vsix 附加到 GitHub Release 页面。

校验不通过时的处理 ​

校验失败原因处理
tag 与版本不一致删除 tag 重新打：git tag -d v1.1.0 && git tag v1.1.0
PAT 失效重新生成 PAT，更新 Secrets
版本已存在递增版本号后重新打 tag
打包体积异常检查 .vscodeignore 与 dependencies

发布后的运营检查 ​

数据观察 ​

text
Marketplace 扩展页 → Overview → 安装量 / 评分 / 下载趋势

后续更新节奏 ​

节奏动作
每次代码合并更新 CHANGELOG 的 Unreleased 区
功能完成vsce publish minor
Bug 修复vsce publish patch
兼容性破坏vsce publish major

从 package.json 元数据到 .vscodeignore，从本地打包到 Marketplace 发布，再到 Actions 自动化，整条链路每一步都有验证点。发布不再是一次性事件，而是随版本迭代循环运转的常规流程。