中文 Git 提交规范,基于 Conventional Commits 1.0.0 规范,针对中文团队的实际使用习惯进行适配。
一、用途与定位
该规范用于统一中文团队的 Git commit message 写法,并配合工具链实现 changelog 自动化。核心原则是:type 保留英文关键字(工具链兼容性好),scope 和 description 使用中文,body 使用中文完整描述。
二、类型(type)定义
文档列出 10 种类型:feat(新功能,如添加用户注册模块)、fix(修复缺陷,如修复登录页白屏问题)、docs(文档变更)、style(代码格式,不影响逻辑)、refactor(重构,非新功能非修复)、perf(性能优化)、test(测试相关)、chore(构建/工具/依赖变更)、ci(持续集成配置)、revert(回滚提交)。
三、commit message 模板
格式为:
<type>(<scope>): <subject>
<body>
<footer>
示例:feat(用户模块): 添加手机号一键登录功能,正文列出接入运营商一键登录 SDK、支持移动联通电信三网、登录失败自动降级到短信验证码,footer 写 Closes #128。
四、Subject 行规范
格式为 <type>(<scope>): <description>。type 必填,从类型表中选取;scope 选填,表示影响范围,使用中文模块名(如用户模块、订单、支付、基础组件);description 必填,中文简述,不超过 50 个字符,使用动宾短语(「添加 xxx」「修复 xxx」「优化 xxx」),不加句号结尾,不要写「修改了代码」这类无意义描述。文档给出好的示例与反面示例(如 fix: 修了一个 bug、feat: 更新代码、chore: 改了点东西)。
五、Body 编写规范
Body 用于详细说明变更的动机、方案和影响。要点包括:说明为什么做这个改动、说明怎么做的、说明影响范围、每行不超过 72 个字符(中文约 36 个汉字)、正文与标题之间空一行。文档提供 Body 模板:改动背景和原因、技术方案要点列表、影响范围。
六、Breaking Changes 标注
当提交包含不兼容变更时,必须在 footer 中标注。格式一:footer 中写 BREAKING CHANGE 并说明具体变更;格式二:在 type 后加感叹号,如 feat(接口)!: 重构用户信息返回结构。团队约定:涉及数据库表结构变更、公共 API 参数/返回值变更、配置文件格式变更时必须标注,且须写明迁移方法或升级步骤。
七、Issue 关联
提供 GitHub 格式(Closes #128、Refs #129, #130)、Gitee 格式(Closes #I5ABC1)、Coding 格式(关联 Coding 缺陷 #12345、fixed=project-2024/issues/678),以及多平台通用写法(# footer 中关联多个平台:Closes #128、Jira: PROJ-456、禅道: #789)。
八、Changelog 自动生成配置
安装命令:npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits。package.json 脚本包含 changelog、changelog:all、release(standard-version)。.versionrc.js 中文配置将各 type 映射到中文分组(如 feat → 新功能、fix → 缺陷修复、perf → 性能优化、refactor → 代码重构、docs → 文档更新、test → 测试,chore/ci/style 设为 hidden)。
九、commitlint 中文配置
安装:npm install -D @commitlint/cli @commitlint/config-conventional。commitlint.config.js 示例设置 type-enum、type-case 为 lower-case、type-empty 与 subject-empty 为 never、subject-max-length 为 100、关闭 subject-case 限制、header-max-length 放宽为 120、body/footer 行长为 200,并配置中文 prompt 提示语(选择提交类型、输入影响范围、填写简短描述、填写详细描述、列出不兼容变更、关联的 Issue、确认提交)。
十、husky + lint-staged 集成
安装与初始化:npm install -D husky lint-staged、npx husky init。commit-msg 钩子运行 npx --no -- commitlint --edit "$1";pre-commit 钩子运行 npx lint-staged;lint-staged 对 js/ts/jsx/tsx/vue 执行 eslint --fix 与 prettier --write,对样式文件执行 stylelint --fix 与 prettier --write,对 md 执行 prettier --write。交互式提交可选安装 commitizen 与 cz-conventional-changelog,运行 npm run commit 进入引导。
十一、团队规范检查清单与落地
提交前自查项包括:type 是否正确、scope 是否准确、subject 是否为动宾短语且不超过 50 字符、末尾是否去掉句号、body 是否说明原因和方案、不兼容变更是否标注、Issue 是否关联、一次提交是否只做一件事。团队落地步骤为工具链配置、模板共享、团队培训、Code Review 关注 commit message 质量、每季度回顾迭代。
十二、常见问题
文档回答:中英文混排时中文与英文/数字之间加一个空格(如「添加 Redis 缓存」);scope 用中文还是英文由团队统一,推荐中文但需在 commitlint 中关闭 scope-case 检查;多人协作靠工具而非自觉,配置 husky + commitlint 可拦截不符合规范的提交。