Git 提交规范（Conventional Commits）

整理 Conventional Commits 的提交格式、类型、作用域和破坏性变更，并提供工作流、Commitlint、Git Hooks 与自动化发布的配置示例。

2026年5月29日更新于 2026年9月5日开发实践,git2分钟阅读

Conventional Commits 用统一格式表达提交的意图、范围和破坏性变更，使提交历史更容易检索、审查和自动化处理。

个人或团队需要统一提交信息时。
需要根据提交历史生成变更日志或触发版本自动化时。
按提交类型检索文档更新、功能开发与问题修复时。

提交类型与 scope 的具体约定见目标仓库的贡献指南、提交钩子和 CI 配置。

Conventional Commits 是一种用于编写提交信息的规范，它提供了一套简单的规则来创建清晰的提交历史。

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

自动生成 CHANGELOG - 通过解析提交信息自动生成变更日志
语义化版本控制 - 根据提交类型自动决定版本号 (major/minor/patch)
清晰的项目历史 - 快速了解每次提交的目的和影响
团队协作效率 - 统一的提交格式降低沟通成本
自动化工作流 - 支持 CI/CD 自动化发布

Type	说明	版本影响	使用场景
`feat`	新功能 (Feature)	MINOR	添加新特性、新页面、新接口
`fix`	修复 Bug	PATCH	修复已知问题、错误处理
`docs`	文档 (Documentation)	-	README、注释、API 文档
`style`	格式	-	缩进、空格、代码格式化
`refactor`	重构	-	优化代码结构、不改变功能
`perf`	性能优化 (Performance)	-	提升运行效率、降低内存占用
`test`	测试	-	添加或修改单元测试、集成测试
`build`	构建系统	-	依赖变更、打包配置
`ci`	CI 配置	-	GitHub Actions、Travis 等
`chore`	杂务	-	辅助工具、配置文件
`revert`	回滚	-	撤销之前的提交

可选，用于标识提交影响的范围，使用小括号包裹，全小写。

feat(auth): 添加第三方登录支持
fix(api): 修复用户查询接口超时
docs(readme): 更新安装说明

常用范围示例：

模块名：auth, user, api, db
功能区：login, payment, notification
层级：frontend, backend, database

使用中文描述
不超过 50 字符
动词开头，使用第一人称现在时
结尾不加句号

✅ feat(auth): 添加第三方登录支持
✅ fix(api): 修复用户查询接口超时问题
❌ fix(api): 修复了用户查询接口超时问题。  # 不要用过去式，不要加句号

可选，详细描述变更内容，使用列表形式说明具体改动。

feat(auth): 添加第三方登录支持

- 集成 GitHub OAuth 登录
- 集成 Google OAuth 登录
- 添加第三方账号绑定功能
- 更新用户信息表结构

Closes #123

可选，用于记录破坏性变更或关联 Issue。

破坏性变更：

feat(db)!: 更换 ORM 框架为 Prisma

BREAKING CHANGE: 数据库迁移脚本需要重新编写
所有现有的 seed 脚本需要更新

关联 Issue：

fix(auth): 修复登录超时问题

Closes #456
Fixes #789

feat(user): 添加用户注册功能

- 实现手机号注册
- 实现邮箱注册
- 添加验证码发送服务

Closes #100

fix(payment): 修复支付回调超时问题

当网络不稳定时，支付回调可能超时，导致订单状态不一致。
增加重试机制和状态同步定时任务。

Fixes #234

docs(api): 更新接口文档

- 添加用户模块接口说明
- 更新错误码列表
- 补充请求示例

refactor(auth): 重构认证模块

- 提取公共验证逻辑到 middleware
- 优化 token 刷新机制
- 统一错误响应格式

perf(query): 优化数据库查询性能

- 添加必要的索引
- 使用 Redis 缓存热点数据
- 优化 N+1 查询问题

响应时间从 500ms 降低到 50ms

test(user): 添加用户模块单元测试

- 覆盖注册流程
- 覆盖登录流程
- 覆盖权限验证

测试覆盖率从 60% 提升到 85%

build(deps): 升级 React 到 v18

- 升级 react 到 18.2.0
- 升级 react-dom 到 18.2.0
- 修复兼容性问题

ci(github): 添加自动化测试流程

- 添加 PR 自动运行测试
- 添加代码覆盖率报告
- 添加自动部署预览环境

chore: 更新 .gitignore 文件

- 添加 IDE 配置文件
- 添加临时文件规则
- 添加日志文件规则

在类型后添加 !，并在 footer 中详细说明。

feat(api)!: 更改用户接口返回格式

BREAKING CHANGE:
- 移除 data 嵌套，直接返回结果
- 错误响应格式统一为 { code, message }
- 需要前端同步更新

迁移指南：https://docs.example.com/migration

feat(auth): 实现 OAuth 2.0 认证

本次提交实现了完整的 OAuth 2.0 认证流程，支持以下功能：

功能列表：
- 支持 Authorization Code 流程
- 支持 PKCE 扩展
- 支持多个 OAuth Provider
- Token 自动刷新

技术实现：
- 使用 passport.js 作为认证框架
- JWT 作为 token 格式
- Redis 存储 session

Closes #123, #456

revert: 回滚 "feat(auth): 添加第三方登录支持"

This reverts commit abc123def456.

原因：第三方登录存在安全漏洞，需要修复后重新上线。

merge: 合并 feature/auth 分支

- 实现用户认证功能
- 添加 JWT 支持
- 集成 OAuth 2.0

feat/功能名称     # 新功能分支
fix/问题描述      # 修复分支
docs/文档内容     # 文档分支
refactor/重构内容 # 重构分支
release/版本号    # 发布分支
hotfix/问题描述   # 紧急修复分支

小步提交 - 每完成一个功能点就提交
原子提交 - 每次提交只做一件事
有意义的提交 - 提交信息能准确描述变更

## 描述
简要描述本次变更的内容

## 变更类型
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 代码重构 (refactor)
- [ ] 性能优化 (perf)
- [ ] 测试相关 (test)
- [ ] 其他 (chore)

## 变更内容
- 变更点 1
- 变更点 2
- 变更点 3

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过

## 关联 Issue
Closes #123

## 截图（如适用）

创建提交模板文件 ~/.gitmessage：

# <type>(<scope>): <subject>
#
# <body>
#
# <footer>

配置 Git 使用模板：

git config --global commit.template ~/.gitmessage

# VS Code
git config --global core.editor "code --wait"

# Vim
git config --global core.editor "vim"

npm install --save-dev @commitlint/cli @commitlint/config-conventional

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // 类型枚举
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新功能
        'fix', // 修复 Bug
        'docs', // 文档
        'style', // 格式
        'refactor', // 重构
        'perf', // 性能优化
        'test', // 测试
        'build', // 构建系统
        'ci', // CI 配置
        'chore', // 杂务
        'revert', // 回滚
      ],
    ],
    // 类型必须小写
    'type-case': [2, 'always', 'lower-case'],
    // 类型不能为空
    'type-empty': [2, 'never'],
    // 主题不能为空
    'subject-empty': [2, 'never'],
    // 主题不以句号结尾
    'subject-full-stop': [2, 'never', '.'],
    // 主题最大长度
    'subject-max-length': [2, 'always', 50],
    // body 最大长度
    'body-max-length': [2, 'always', 100],
    // scope 小写
    'scope-case': [2, 'always', 'lower-case'],
  },
};

npm install --save-dev husky
npx husky install

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

{
  "scripts": {
    "prepare": "husky install"
  },
  "devDependencies": {
    "@commitlint/cli": "^19.0.0",
    "@commitlint/config-conventional": "^19.0.0",
    "husky": "^9.0.0"
  }
}

npm install --save-dev standard-version

{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major",
    "release:patch": "standard-version --release-as patch"
  }
}

{
  "types": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "perf", "section": "Performance" },
    { "type": "docs", "section": "Documentation" },
    { "type": "refactor", "section": "Refactoring" },
    { "type": "test", "section": "Tests" },
    { "type": "chore", "hidden": true },
    { "type": "style", "hidden": true },
    { "type": "ci", "hidden": true },
    { "type": "build", "hidden": true }
  ],
  "commitUrlFormat": "https://github.com/{{owner}}/{{repo}}/commit/{{hash}}",
  "compareUrlFormat": "https://github.com/{{owner}}/{{repo}}/compare/{{previousTag}}...{{currentTag}}",
  "issueUrlFormat": "https://github.com/{{owner}}/{{repo}}/issues/{{id}}"
}

name: Test

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Run build
        run: npm run build

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Release
        run: npx standard-version
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Push changes
        run: git push --follow-tags origin main

name: PR Lint

on:
  pull_request:
    types: [opened, edited, synchronize, reopened]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm install @commitlint/config-conventional

      - name: Lint PR title
        uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          types: |
            feat
            fix
            docs
            style
            refactor
            perf
            test
            build
            ci
            chore
            revert
          requireScope: false
          subjectPattern: ^(?![A-Z]).+$
          subjectPatternError: |
            The subject "{subject}" found in the pull request title "{title}"
            doesn't match the configured pattern. The subject must not start with an uppercase letter.

## 描述

<!-- 简要描述本次变更的内容 -->

## 变更类型

<!-- 请勾选适用的类型 -->

- [ ] ✨ 新功能 (feat)
- [ ] 🐛 Bug 修复 (fix)
- [ ] 📝 文档更新 (docs)
- [ ] 💄 格式调整 (style)
- [ ] ♻️ 代码重构 (refactor)
- [ ] ⚡ 性能优化 (perf)
- [ ] ✅ 测试相关 (test)
- [ ] 🔧 构建配置 (build)
- [ ] 👷 CI 配置 (ci)
- [ ] 🔩 杂务 (chore)
- [ ] ⏪ 回滚 (revert)

## 变更内容

<!-- 详细列出本次变更的内容 -->

-
-
-

## 测试

<!-- 描述如何测试本次变更 -->

- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过

## 关联 Issue

<!-- 关联的 Issue 编号 -->

Closes #

## 截图

<!-- 如果适用，请添加截图 -->

## 检查清单

- [ ] 我的代码遵循项目的代码风格
- [ ] 我已经进行了自我审查
- [ ] 我已经添加了必要的注释
- [ ] 我已经更新了必要的文档
- [ ] 我的变更不会产生新的警告
- [ ] 我已经添加了证明我的修复有效或我的功能能工作的测试
- [ ] 新的和现有的单元测试在我的变更下都能通过

# 使用 standard-version
npm run release

# 使用 conventional-changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npm run lint
npm run test

# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no -- commitlint --edit $1

# .husky/pre-push
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npm run test

# 修改最后一次提交信息
git commit --amend -m "正确的提交信息"

# 如果已经推送
git commit --amend -m "正确的提交信息"
git push --force-with-lease

# 撤销提交但保留改动
git reset --soft HEAD~1

# 撤销提交并丢弃改动
git reset --hard HEAD~1

# 安全撤销（生成新提交）
git revert <commit-hash>

# 交互式 rebase，合并最近 3 次提交
git rebase -i HEAD~3

# 在编辑器中将 pick 改为 squash
# pick abc1234 feat: 第一次提交
# squash def5678 feat: 第二次提交
# squash ghi9012 feat: 第三次提交

# 从 main 创建 hotfix 分支
git checkout -b hotfix/critical-bug main

# 修复并提交
git commit -m "fix: 修复紧急安全漏洞"

# 合并到 main
git checkout main
git merge hotfix/critical-bug

# 合并到 develop
git checkout develop
git merge hotfix/critical-bug