插件更新与版本管理

插件发布只是起点，迭代才是常态。一次成功的更新涉及版本号决策、变更记录撰写、构建脚本与质量检查四个环节，每个环节都有明确的规范。

版本号自动递增

vsce 递增语法

vsce publish 支持三种递增粒度，命令执行后会同时改写 package.json 中的 version 并上传新版本：

# 缺陷修复：1.0.0 → 1.0.1
vsce publish patch

# 新增功能：1.0.0 → 1.1.0
vsce publish minor

# 破坏性变更：1.0.0 → 2.0.0
vsce publish major

命令	版本变化	典型场景
vsce publish patch	1.0.0 → 1.0.1	修 Bug、小调整
vsce publish minor	1.0.0 → 1.1.0	新功能，兼容旧行为
vsce publish major	1.0.0 → 2.0.0	破坏性 API 变更

递增规则细节

• patch：只加最后一位，1.2.3 → 1.2.4
• minor：中间位加一，patch 归零，1.2.3 → 1.3.0
• major：首位加一，其余归零，1.2.3 → 2.0.0

什么时候用 major

以下情况必须升 major：

• 修改了 contributes 中的命令 ID、配置键名
• 删除了旧 API 或旧的激活事件
• 改变了默认行为，导致用户配置失效

破坏性变更如果只升 patch，会让用户的自动化脚本悄悄失灵，信任度受损。

预发布版本

# 内测版
vsce publish 1.1.0-beta.1

# 候选版
vsce publish 1.1.0-rc.1

预发布版本用于正式发布前的验证，安装体验与正式版一致。

CHANGELOG.md 编写规范

Marketplace 会自动把 CHANGELOG.md 渲染到插件页的 Changelog 标签页，用户更新插件时也会看到。规范的变更记录采用 Keep a Changelog 格式。

Keep a Changelog 结构

# Changelog

本项目所有重要变更都会记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。

## [1.1.0] - 2026-03-15

### 新增

- 支持 JSON 文件实时预览
- 新增格式化历史撤销功能
- 深色主题适配

### 修复

- 修复大文件格式化时编辑器卡顿的问题
- 修复状态栏图标在缩放 150% 时错位的问题

### 变更

- 默认缩进从 4 空格调整为 2 空格

## [1.0.1] - 2026-02-01

### 修复

- 修复 Windows 路径含中文时格式化失败的问题

## [1.0.0] - 2026-01-10

### 新增

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

版本标题与日期

每个版本块以 ## [版本号] - 日期 开头，日期用 ISO 格式 YYYY-MM-DD。最新版本在最上方，未发布版本写 [Unreleased]：

## [Unreleased]

### 新增

- 准备中的功能（尚未发布）

分类标准

Keep a Changelog 定义了六个分类，按常用程度排序：

分类	含义	示例
新增（Added）	新功能	新增快捷键绑定
变更（Changed）	现有行为变化	修改默认配置
废弃（Deprecated）	即将移除的功能	旧命令标记废弃
移除（Removed）	已移除的功能	删除废弃命令
修复（Fixed）	Bug 修复	修复崩溃问题
安全（Security）	安全相关修复	升级依赖消除漏洞

编写要点

• 用用户能理解的语言，不写内部实现细节
• 每条变更一句话，动词开头："修复"、"新增"、"调整"
• 关联 issue 时附上链接
• 与版本号对应：[1.1.0] 的标题必须和 package.json 的 version 一致

关联 GitHub 链接区（可选）

大型项目常在文件尾部维护链接引用：

[1.1.0]: https://github.com/zhangsan/my-extension/compare/v1.0.1...v1.1.0
[1.0.1]: https://github.com/zhangsan/my-extension/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/zhangsan/my-extension/releases/tag/v1.0.0

vscode:prepublish 构建脚本

发布前必须先编译，否则上传的是过期产物。vscode:prepublish 是 vsce 的约定脚本，在 vsce package 与 vsce publish 执行时自动触发。

基础配置

{
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./"
  }
}

生产环境构建

仅编译还不够：开发依赖（@types/vscode、typescript 等）不应进入产物。发布时用 --production 安装依赖再编译：

{
  "scripts": {
    "vscode:prepublish": "npm install --production && npm run compile"
  }
}

但这会让每次打包都重新安装依赖。更常见的做法是把产物与依赖交给 .vscodeignore 管理，vscode:prepublish 只负责编译：

{
  "scripts": {
    "vscode:prepublish": "npm run compile && npm prune --omit=dev",
    "compile": "esbuild src/extension.ts --bundle --outfile=dist/extension.js --external:vscode"
  }
}

用 esbuild 加速构建

TypeScript 插件用 esbuild 打包可以显著减少体积并加快启动：

{
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "node esbuild.js",
    "watch": "node esbuild.js --watch"
  }
}

// esbuild.js —— 构建脚本示例
const esbuild = require('esbuild');

const options = {
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'dist/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
  sourcemap: false,
  minify: true,
  logLevel: 'info'
};

if (process.argv.includes('--watch')) {
  esbuild.context(options).then(ctx => ctx.watch());
} else {
  esbuild.build(options).catch(() => process.exit(1));
}

external: ['vscode'] 告诉 esbuild 不要把 vscode 模块打进包里——它在 VS Code 宿主运行时提供，打入会导致运行时错误。

验证构建链路

发布前手动跑一遍构建，确认编译无误：

npm run vscode:prepublish
vsce ls

vsce ls 的输出应只包含 dist/ 产物、package.json、README.md 与 CHANGELOG.md。

发布前质量检查清单

发布即承诺，以下是发布前必须逐项核对的内容。

引擎版本

node -e "const p=require('./package.json'); console.log(p.engines.vscode)"

核对 engines.vscode 与 @types/vscode 是否一致。使用了 vscode API 的哪个版本，engines.vscode 就应不低于该版本。在 package.json 中确认：

{
  "engines": { "vscode": "^1.85.0" }
}

图标尺寸

icon 必须是 PNG，128x128 像素，小于 256KB。可以用 Node 脚本校验：

// scripts/check-icon.js —— 校验图标是否符合发布要求
const fs = require('fs');
const pkg = require('../package.json');

if (!pkg.icon) {
  console.error('缺少 icon 字段');
  process.exit(1);
}
const size = fs.statSync(pkg.icon).size;
if (size > 256 * 1024) {
  console.error('icon 超过 256KB：' + size);
  process.exit(1);
}
console.log('icon OK：' + pkg.icon + ' (' + size + ' bytes)');

许可证

• package.json 声明了 license 字段（如 MIT）
• 根目录存在对应 LICENSE 文件
• 依赖了开源库时，注意其许可证与插件许可证的兼容性

README 完整度

• README 存在且首屏完整
• 图片链接可访问（相对路径图片会被打包进插件）
• 不包含非法 HTML（尖括号需要转义或用代码块包裹）

功能回归

检查项	操作
冷启动	全新环境安装后正常激活
旧配置兼容	用上一版本的配置跑一遍核心功能
热更新	修改配置后功能即时生效
卸载干净	卸载后无残留配置文件
错误路径	无文件、无选择项等边界场景不崩溃

打包体积复核

vsce package --out /tmp/check.vsix
ls -lh /tmp/check.vsix

产物大小与上版对比，异常增大说明依赖或资源混入了包。

发布前最终检查脚本

把检查项固化成一个脚本，每次发布前执行：

{
  "scripts": {
    "prepublishOnly": "npm run compile && node scripts/check-icon.js && vsce package --out /tmp/check.vsix"
  }
}

版本管理是插件的信用体系：语义化版本告诉用户变更的烈度，CHANGELOG 记录每步演进的依据，构建脚本保证产物与源码一致，检查清单守住发布质量底线。