当前位置：首页 > news >正文

Git 提交规范

news 2026/6/17 11:29:17

Git 提交规范的核心目标是 统一提交信息格式、提升代码可追溯性、降低团队协作成本，尤其适合多人协作项目或长期维护的代码库。以下是业界通用的标准化规范（基于 Angular 提交规范衍生，最主流方案），包含格式定义、类型说明、实操技巧和工具辅助，兼顾易用性和规范性：

一、核心提交信息格式（强制规范）

一个合格的 Git 提交信息（Commit Message）分为 3 部分：类型(范围): 描述（必填） + 空行 + 详细说明（可选） + 空行 + 关联标识（可选），格式如下：

bash
 
运行

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

各部分说明：

部分	要求与示例
`type`（类型）	必须，标识提交的核心目的（如下表细分），全小写英文
`scope`（范围）	可选，指定提交影响的模块 / 功能（如 `user`、`order`、`api`、`frontend`），无则省略括号
`subject`（描述）	必须，简洁概括提交内容（100 字符内），首字母小写，结尾不加标点，用祈使句（如 “修复” 而非 “修复了”）
`body`（详细说明）	可选，补充 `subject` 未说明的细节（如修改原因、实现逻辑、影响范围），换行分隔
`footer`（关联标识）	可选，关联 Issue / 需求 ID（如 `Closes #123`）、标注不兼容变更（`BREAKING CHANGE: ...`）

二、`type` 类型定义（核心重点）

类型	适用场景	示例
`feat`	新增功能（如新增接口、新增页面、新增组件）	`feat(user): 新增用户注册接口`
`fix`	修复 Bug（如逻辑错误、语法错误、兼容性问题）	`fix(order): 修复订单支付状态同步异常`
`docs`	仅修改文档（如 README、注释、接口文档，不涉及代码逻辑）	`docs: 更新 API 接口参数说明`
`style`	代码格式调整（如缩进、空格、命名规范、格式化，不改变代码逻辑）	`style: 统一变量命名为小驼峰`
`refactor`	重构代码（既不新增功能，也不修复 Bug，如重构函数、优化逻辑、拆分模块）	`refactor(api): 拆分用户模块接口逻辑`
`perf`	性能优化（如减少接口响应时间、降低内存占用、优化查询效率）	`perf(db): 优化订单表查询索引`
`test`	新增 / 修改测试用例（如单元测试、集成测试）	`test(user): 补充用户登录单元测试`
`build`	构建相关修改（如依赖包更新、构建脚本调整、Docker 配置修改）	`build: 升级 requests 依赖到 2.31.0`
`ci`	CI/CD 配置修改（如 GitHub Actions、Jenkins 脚本调整）	`ci: 新增代码提交前 lint 检查`
`chore`	其他不影响代码逻辑的修改（如删除无用文件、配置文件调整、日志格式修改）	`chore: 删除废弃的测试数据文件`
`revert`	回滚之前的提交	`revert: feat(user): 回滚新增注册接口`

三、提交规范实操示例

1. 基础示例（仅必填部分）

bash
 
运行

git commit -m "fix(frontend): 修复登录页验证码刷新失败问题"

2. 完整示例（含 body 和 footer）

bash
 
运行

git commit -m "feat(order): 新增订单批量导出功能1. 支持按时间范围筛选订单导出
2. 导出格式支持 Excel/CSV 两种类型
3. 优化导出文件命名规则（订单_20251205_1000.xlsx）Closes #456  # 关联需求 ID 456，提交后自动关闭该需求
"
 

3. 不兼容变更示例（footer 标注）

bash
 
运行

git commit -m "refactor(api): 重构用户信息接口将 /api/v1/user 接口改为 /api/v2/user，参数结构调整为 JSON 格式BREAKING CHANGE: 接口路径和参数格式不兼容旧版本，需前端同步更新
Closes #789
"
 

四、禁止与注意事项

禁止使用模糊描述（如 “修改了一些问题”“优化代码”“更新”），必须明确具体内容；
禁止提交信息包含无关内容（如吐槽、表情、中文标点混排）；
禁止单次提交包含多个不相关修改（如同时新增功能 + 修复其他模块 Bug，应拆分多次提交）；
subject 首字母小写，结尾不加句号 / 感叹号，用祈使句（“新增”“修复”“优化” 而非 “新增了”“修复了”）；
涉及敏感信息（如密码、密钥）的修改，需在提交前确认已移除敏感内容，避免泄露。

五、工具辅助（自动校验 + 生成格式）

手动维护规范易出错，推荐用工具强制校验和自动生成提交格式：

1. Commitizen（自动生成规范格式）

安装：激活虚拟环境后执行

bash
 
运行

pip install commitizen  # Python 项目推荐
# 或 Node 项目：npm install -g commitizen

使用：替代 git commit，按交互提示填写信息
bash

运行
```
cz commit  # 或简写 cz c
```
工具会自动引导选择 type、scope、输入 subject 等，无需记忆格式

2. pre-commit（提交前校验）

作用：提交前自动检查提交信息是否符合规范，不符合则拒绝提交；
配置步骤：
1. 安装 pre-commit：pip install pre-commit
2. 在项目根目录创建 .pre-commit-config.yaml 文件，添加以下内容：
  yaml
  repos: - repo: https://github.com/commitizen-tools/commitizenrev: v3.28.0hooks:- id: commitizenstages: [commit-msg]
3. 执行 pre-commit install 启用钩子；
  
  之后提交时，工具会自动校验提交信息，不符合规范会提示错误并终止提交。

3. 其他工具

commitlint：Node 项目常用，配合 husky 实现提交信息校验；
standard-version/semantic-release：根据提交记录自动生成版本号和 CHANGELOG.md（无需手动编写更新日志）。

六、团队协作补充建议

统一 scope 定义：团队提前约定 scope 可选值（如 frontend/backend/api/db），避免混乱；
小步提交：尽量保持单次提交的修改范围小（如 “修复一个 Bug”“新增一个小功能”），便于回溯和回滚；
关联需求 / Issue：提交时通过 Closes #ID/Fixes #ID 关联项目管理工具（如 Jira、GitHub Issues）的任务 ID，实现代码与需求的联动追溯；
定期 Review 提交记录：团队内定期检查提交规范执行情况，及时纠正不规范提交。

总结

Git 提交规范的核心是 “让提交信息有意义、可追溯”，通过 type(scope): subject 的固定格式 + 工具辅助，既能降低团队沟通成本，也能为后续代码维护、版本迭代提供清晰的历史依据。新手建议先牢记 type 类型和基础格式，再通过 Commitizen 等工具简化操作，逐步养成规范提交的习惯。