Appearance
附录 D：提交信息规范详解
规范的提交信息是高质量项目的重要组成部分。本附录详细介绍 Conventional Commits 规范及其实际应用。
Conventional Commits 规范
Conventional Commits 是一套基于语义化版本的提交信息规范。
格式
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]Type 类型一览
| Type | 说明 | 触发版本升级 |
|---|---|---|
feat | 新功能 | minor |
fix | Bug 修复 | patch |
docs | 文档变更 | 不升级 |
style | 代码格式（不影响功能） | 不升级 |
refactor | 重构（既非新功能也非 Bug 修复） | 不升级 |
perf | 性能优化 | patch |
test | 添加或修改测试 | 不升级 |
build | 构建系统或外部依赖变更 | 不升级 |
ci | CI 配置文件和脚本变更 | 不升级 |
chore | 其他维护工作（不修改 src 或 test 文件） | 不升级 |
revert | 回退某次提交 | 视情况 |
破坏性变更（Breaking Change）
触发 major 版本升级：
# 在 type 后加 !
feat!: 重构用户认证 API
# 或者在 footer 中说明
feat(auth): 重构用户认证 API
BREAKING CHANGE: AuthService 接口已更改，调用方需更新方法签名完整示例
简单提交（只有 subject）
feat: 添加用户注册功能
fix: 修复登录时的空指针异常
docs: 更新 README 中的安装说明
chore: 升级依赖到最新版本
test: 添加用户服务的单元测试
refactor: 提取公共工具函数到 utils.js带 scope 的提交
feat(auth): 实现 JWT Token 刷新机制
fix(cart): 修复购物车数量计算错误
docs(api): 补充 /users 端点的参数说明
style(button): 统一按钮组件的 padding 值带 body 的提交
feat(payment): 集成支付宝支付
支持用户通过支付宝完成订单支付。
实现了回调验签和订单状态更新逻辑。
相关文档：docs/payment/alipay.md带 footer 的提交
fix(auth): 修复 Token 过期后未能正确跳转登录页
问题原因：axios 拦截器中未正确处理 401 状态码，
导致 Token 过期后用户仍停留在当前页面。
Closes #234
Reviewed-by: Alice <alice@example.com>破坏性变更
feat(api)!: 将 /api/v1 升级为 /api/v2
新版本 API 重新设计了响应格式，统一使用 { code, data, message } 结构。
BREAKING CHANGE: 所有 API 响应格式已更改，客户端需要更新解析逻辑。
旧格式：{ status: 'ok', result: {} }
新格式：{ code: 0, data: {}, message: 'success' }
Migration guide: https://docs.example.com/migration/v2Subject 写作规范
好的 subject：
✅ feat: 添加用户头像上传功能
✅ fix: 修复移动端导航栏遮挡内容的问题
✅ refactor: 将 UserService 拆分为多个职责单一的服务不好的 subject：
❌ 修改了一些东西 # 太模糊
❌ fix bug # 没有说明是什么 bug
❌ WIP # 未完成的工作不应提交
❌ feat: 添加了用户头像上传功能并修复了相关的上传失败的bug以及优化了上传速度 # 太长规则：
- 动词开头，使用祈使语气（"添加"而不是"添加了"）
- 不超过 72 个字符
- 不以句号结尾
- 英文首字母小写（如果使用英文）
引用 Issue 和 PR
# GitHub 风格
Closes #123
Fixes #123
Resolves #123
# 关闭多个
Closes #123, #456
# 只引用不关闭
Related to #123
See also #456
# GitLab 风格
Closes gitlab#123工具配置
commitlint（强制规范）
bash
# 安装
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# 配置文件 commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2, 'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']
],
'subject-max-length': [2, 'always', 100],
'subject-case': [0], // 不限制大小写（中文友好）
},
};Husky + commitlint（在提交时自动验证）
bash
# 安装
npm install --save-dev husky
# 初始化 Husky
npx husky init
# 添加 commit-msg 钩子
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msgCommitizen（交互式填写提交信息）
bash
# 全局安装
npm install -g commitizen cz-conventional-changelog
# 全局配置（~/.czrc）
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
# 之后使用 git cz 代替 git commit
git czconventional-changelog（自动生成 CHANGELOG）
bash
# 安装
npm install -g conventional-changelog-cli
# 生成 CHANGELOG（追加模式）
conventional-changelog -p angular -i CHANGELOG.md -s
# 从头生成完整 CHANGELOG
conventional-changelog -p angular -i CHANGELOG.md -s -r 0团队落地建议
快速起步（推荐）
bash
# 1. 安装工具
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
# 2. 初始化 Husky
npx husky init
# 3. 配置 commitlint
cat > commitlint.config.js << 'EOF'
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'subject-case': [0],
},
};
EOF
# 4. 配置钩子
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
# 5. 提交配置
git add commitlint.config.js .husky/commit-msg
git commit -m "chore: 添加 commitlint 提交规范"CHANGELOG 规范的 Emoji 增强版
有些团队喜欢在提交中加入 emoji，增加可读性：
✨ feat: 添加用户注册功能
🐛 fix: 修复登录问题
📚 docs: 更新文档
🎨 style: 代码格式化
♻️ refactor: 重构认证模块
⚡ perf: 优化查询速度
✅ test: 添加单元测试
🔧 chore: 更新配置可以使用 gitmoji 工具：
bash
# 安装
npm install -g gitmoji-cli
# 使用（替代 git commit）
gitmoji -c常见 FAQ
Q: 一次提交可以同时有 feat 和 fix 吗？
A: 不建议。一次提交应该只做一件事。如果有多个变更，分多次提交。
Q: 重构代码时发现了 bug 顺手修了，怎么写？
A: 分两次提交：
refactor(xxx): ...fix(xxx): ...
Q: 提交了错误的类型，能改吗？
A: 如果还没推送：git commit --amend 如果已推送且是公共分支：创建一个新的修正提交或接受错误（不要改历史）
Q: 中文还是英文？
A: 根据团队情况。中文团队用中文更清晰；开源项目建议用英文。关键是全团队保持一致。