语义化版本和 Changelog
约 915 字大约 3 分钟
版本管理语义化版本Changelog
2026-04-15
概述
语义化版本（SemVer）和规范化 Changelog 是团队协作和开源项目管理的基础。
语义化版本规范 (SemVer)
版本格式
主版本号.次版本号.修订号
MAJOR.MINOR.PATCH
示例: 1.2.3| 级别 | 变化 | 说明 |
|---|---|---|
| MAJOR | 破坏性变更 | 不兼容的 API 修改 |
| MINOR | 新功能 | 向下兼容的功能新增 |
| PATCH | 补丁修复 | 向下兼容的问题修复 |
版本号递增规则
# 1.2.3 → 1.2.4 (PATCH)
# 修复 bug，不改变 API
# 例如: 修复按钮点击无反应
# 1.2.3 → 1.3.0 (MINOR)
# 新增功能，保持向后兼容
# 例如: 新增 Button 的 size 属性
# 1.2.3 → 2.0.0 (MAJOR)
# 破坏性变更，不兼容旧版
# 例如: 删除废弃的 API、重命名 props先行版本
# Alpha (内部测试)
1.0.0-alpha.1
1.0.0-alpha.2
# Beta (公开测试)
1.0.0-beta.1
1.0.0-beta.2
# RC (候选发布)
1.0.0-rc.1
1.0.0-rc.2
# 最终版本
1.0.0常见场景
# 初始开发阶段
0.1.0 # 首个预览版本
0.2.0 # 新增功能
0.2.1 # 修复问题
# 1.0.0 正式发布
1.0.0 # 正式版
# 后续迭代
1.0.1 # patch 修复
1.1.0 # minor 新功能
2.0.0 # major 重构package.json 版本管理
版本范围
{
"dependencies": {
"vue": "^3.4.0", "^": 兼容更新，锁定主版本
"lodash": "~4.17.21", "~": 兼容补丁，锁定主次版本
"react": "18.2.0", #: 精确版本
"pinia": ">=2.0.0", #>=: 最低要求
"axios": ">=1.0.0 <2.0.0"
}
}版本锁定
# npm
npm shrinkwrap # 生成 npm-shrinkwrap.json
npm ci # 根据 lockfile 安装
# yarn
yarn.lock # 自动生成
yarn install --frozen-lockfile
# pnpm
pnpm-lock.yaml # 自动生成
pnpm install --frozen-lockfileChangelog 规范
Keep a Changelog 格式
# Changelog
所有重大项目更改都应记录在此文件中。
## [1.2.0] - 2024-01-15
### 新增
- 支持 TypeScript 4.9
- 新增 `useConfig` 组合式函数
- 添加暗黑主题支持
### 修改
- `Button` 组件默认尺寸从 `large` 改为 `medium`
- 优化打包体积，减少 20%
### 废弃
- `OldComponent` 已废弃，请使用 `NewComponent` 替代
### 修复
- 修复 Input 组件在 iOS 上的样式问题
- 修复 Modal 关闭按钮无法点击的问题
### 破坏性变更
- 移除 `theme` 属性，请使用 `class` 和 `style`
- `onChange` 回调参数从 `(value)` 改为 `(value, event)`版本块结构
## [版本号] - 日期
### 新增 (Added)
- 新功能
### 修改 (Changed)
- 功能变更
### 废弃 (Deprecated)
- 不推荐使用的内容
### 移除 (Removed)
- 已删除的功能
### 修复 (Fixed)
- bug 修复
### 安全 (Security)
- 安全相关修复自动化工具
standard-version
# 安装
npm install --save-dev standard-version
# 使用
npx standard-version # 生成 CHANGELOG 和 tag
npx standard-version --release-as 2.0.0 # 指定版本
npx standard-version --prerelease # 预发布版本release-please
# 安装
npm install --save-dev release-please
# 配置 .release-please-manifest.json
{
".": "1.0.0"
}
# 运行
npx release-pleaseChangesets
# 安装
npm install --save-dev @changesets/cli
# 初始化
npx changeset init
# 添加变更
npx changeset add
# 发布
npx changeset version
npx changeset publishcommitizen
# 安装
npm install --save-dev commitizen cz-conventional-changelog
# 配置 package.json
{
"scripts": {
"commit": "cz"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
}
}提交信息规范
格式
<类型>(<范围>): <描述>
[可选正文]
[可选脚注]类型
| 类型 | 说明 |
|---|---|
| feat | 新功能 |
| fix | 修复问题 |
| docs | 文档修改 |
| style | 格式修改（不影响代码） |
| refactor | 重构 |
| perf | 性能优化 |
| test | 测试相关 |
| build | 构建相关 |
| ci | CI 配置 |
| chore | 其他修改 |
示例
feat(button): add size prop
Add 'size' prop to Button component to control button size.
Closes #123工具
# commitlint
npm install --save-dev @commitlint/config-conventional @commitlint/cli
# .commitlintrc.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
},
};GitHub Release
创建 Release
# 1. 创建 tag
git tag v1.2.0 -m "Release 1.2.0"
# 2. 推送 tag
git push origin v1.2.0
# 3. GitHub 会自动触发 release 事件GitHub Actions 自动发布
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}