chinese-commit-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

中文 Git 提交规范

Chinese Git Commit Guidelines

1. Conventional Commits 中文适配

1. Chinese Adaptation of Conventional Commits

基于 Conventional Commits 1.0.0 规范，针对中文团队的实际使用习惯进行适配。

Based on Conventional Commits 1.0.0 specification, adapted for the actual usage habits of Chinese teams.

类型（type）定义

Type Definitions

类型	说明	示例场景
`feat`	新功能	添加用户注册模块
`fix`	修复缺陷	修复登录页白屏问题
`docs`	文档变更	更新 API 接口文档
`style`	代码格式（不影响逻辑）	调整缩进、补充分号
`refactor`	重构（非新功能、非修复）	拆分过长的服务类
`perf`	性能优化	优化首页列表查询速度
`test`	测试相关	补充用户模块单元测试
`chore`	构建/工具/依赖变更	升级 webpack 到 v5
`ci`	持续集成配置	修改 GitHub Actions 流程
`revert`	回滚提交	回滚 v2.1.0 的登录重构

Type	Description	Example Scenarios
`feat`	New Feature	Add user registration module
`fix`	Bug Fix	Fix white screen issue on login page
`docs`	Documentation Change	Update API interface docs
`style`	Code Format (no logic impact)	Adjust indentation, add semicolons
`refactor`	Refactoring (not new feature/fix)	Split overly long service class
`perf`	Performance Optimization	Optimize homepage list query speed
`test`	Testing Related	Add unit tests for user module
`chore`	Build/Tool/Dependency Change	Upgrade webpack to v5
`ci`	CI Configuration	Modify GitHub Actions workflow
`revert`	Revert Commit	Revert login refactor in v2.1.0

原则

Principles

type 保留英文关键字（工具链兼容性好）
scope 和 description 使用中文
body 使用中文完整描述

Keep English keywords for
```
type
```
(better compatibility with toolchains)
Use Chinese for
```
scope
```
and
```
description
```
Use Chinese for detailed description in
```
body
```

2. 中文 commit message 模板

2. Chinese Commit Message Template

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

<body>

<footer>

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

<body>

<footer>

完整示例

Complete Examples

feat(用户模块): 添加手机号一键登录功能

- 接入运营商一键登录 SDK
- 支持移动、联通、电信三网
- 登录失败自动降级到短信验证码

Closes #128

fix(订单): 修复并发下单导致库存超卖的问题

在高并发场景下，原有的库存扣减逻辑存在竞态条件。
改用 Redis 分布式锁 + 数据库乐观锁双重保障。

影响范围：订单服务、库存服务
测试确认：已通过 500 并发压测验证

Closes #256

feat(User Module): Add one-click login via phone number

- Integrated carrier one-click login SDK
- Supports China Mobile, China Unicom, China Telecom
- Automatically downgrade to SMS verification code on login failure

Closes #128

fix(Order): Fix inventory oversold issue caused by concurrent orders

In high-concurrency scenarios, the original inventory deduction logic had race conditions.
Adopted dual protection of Redis distributed lock + database optimistic lock.

Affected Scope: Order Service, Inventory Service
Test Verification: Passed 500 concurrent pressure tests

Closes #256

3. Subject 行规范

3. Subject Line Guidelines

格式

Format

<type>(<scope>): <description>

<type>(<scope>): <description>

规则

Rules

type: 必填，从上方类型表中选取
scope: 选填，表示影响范围，使用中文模块名
- 示例：
```
用户模块
```
  、
```
订单
```
  、
```
支付
```
  、
```
基础组件
```
description: 必填，中文简述，不超过 50 个字符
- 使用动宾短语：「添加 xxx」「修复 xxx」「优化 xxx」
- 不加句号结尾
- 不要写「修改了代码」这种无意义描述

type: Required, select from the type table above
scope: Optional, indicates affected scope, use Chinese module names
- Examples:
```
User Module
```
  ,
```
Order
```
  ,
```
Payment
```
  ,
```
Basic Components
```
description: Required, brief Chinese description, no more than 50 characters
- Use verb-object phrases: "Add xxx", "Fix xxx", "Optimize xxx"
- No period at the end
- Avoid meaningless descriptions like "Modified code"

好的示例

Good Examples

feat(权限): 添加基于 RBAC 的细粒度权限控制
fix(支付): 修复微信支付回调签名验证失败的问题
perf(列表页): 优化大数据量表格的虚拟滚动渲染
refactor(网关): 将单体网关拆分为独立微服务

feat(Permission): Add fine-grained permission control based on RBAC
fix(Payment): Fix WeChat Pay callback signature verification failure issue
perf(List Page): Optimize virtual scrolling rendering for large-data tables
refactor(Gateway): Split monolithic gateway into independent microservices

反面示例

Bad Examples

undefined

undefined

以下写法应避免

Avoid the following

fix: 修了一个 bug feat: 更新代码 chore: 改了点东西

undefined

fix: Fixed a bug feat: Updated code chore: Changed something

undefined

4. Body 编写规范

4. Body Writing Guidelines

Body 用于详细说明本次变更的动机、方案和影响。

The

body

is used to explain the motivation, solution, and impact of the change in detail.

编写要点

Key Writing Points

说明为什么要做这个改动（背景/原因）
说明怎么做的（技术方案摘要）
说明影响范围（哪些模块、接口受影响）
每行不超过 72 个字符（中文约 36 个汉字）
正文与标题之间空一行

Explain why the change is made (background/reason)
Explain how it's done (technical solution summary)
Explain affected scope (which modules/interfaces are impacted)
No more than 72 characters per line (about 36 Chinese characters)
Leave a blank line between body and subject

Body 模板

Body Template

<改动背景和原因>

技术方案：
- <方案要点 1>
- <方案要点 2>

影响范围：<受影响的模块或服务>

<Change background and reason>

Technical Solution:
- <Solution point 1>
- <Solution point 2>

Affected Scope: <Impacted modules or services>

5. Breaking Changes 标注

5. Breaking Changes Marking

当提交包含不兼容变更时，必须在 footer 中标注。

When a commit contains incompatible changes, it must be marked in the

footer

格式一：footer 标注

Format 1: Footer Marking

feat(接口): 重构用户信息返回结构

将用户接口返回的扁平结构改为嵌套结构，前端需同步调整字段取值路径。

BREAKING CHANGE: /api/user/info 返回结构变更
- avatar 字段移入 profile 对象
- 移除已废弃的 nickname 字段，统一使用 displayName

feat(API): Refactor user information return structure

Changed the flat structure returned by the user API to a nested structure; front-end needs to adjust field access paths accordingly.

BREAKING CHANGE: /api/user/info return structure changed
- avatar field moved into profile object
- Removed deprecated nickname field, unified use of displayName

格式二：type 后加感叹号

Format 2: Add Exclamation Mark After Type

feat(接口)!: 重构用户信息返回结构

feat(API)!: Refactor user information return structure

团队约定

Team Agreements

涉及数据库表结构变更 -> 必须标注 BREAKING CHANGE
涉及公共 API 参数/返回值变更 -> 必须标注
涉及配置文件格式变更 -> 必须标注
标注时须写明迁移方法或升级步骤

Database table structure changes -> Must mark BREAKING CHANGE
Public API parameter/return value changes -> Must mark
Configuration file format changes -> Must mark
Must include migration methods or upgrade steps when marking

6. Issue 关联

6. Issue Association

GitHub 格式

GitHub Format

Closes #128
Refs #129, #130

Closes #128
Refs #129, #130

Gitee 格式

Gitee Format

Closes #I5ABC1
相关需求: https://gitee.com/org/repo/issues/I5ABC1

Closes #I5ABC1
Related Requirement: https://gitee.com/org/repo/issues/I5ABC1

Coding 格式

Coding Format

关联 Coding 缺陷 #12345
fixed=project-2024/issues/678

Link Coding Defect #12345
fixed=project-2024/issues/678

通用写法

General Writing

undefined

undefined

footer 中关联多个平台

Associate multiple platforms in footer

Closes #128 Jira: PROJ-456 禅道: #789

undefined

Closes #128 Jira: PROJ-456 ZenTao: #789

undefined

7. Changelog 自动生成配置

7. Changelog Auto-Generation Configuration

安装 conventional-changelog

Install conventional-changelog

bash

npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits

bash

npm install -D conventional-changelog-cli conventional-changelog-conventionalcommits

package.json 脚本

package.json Scripts

json

{
  "scripts": {
    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s -r 0",
    "release": "standard-version"
  }
}

json

{
  "scripts": {
    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s -r 0",
    "release": "standard-version"
  }
}

.versionrc.js 中文配置

.versionrc.js Chinese Configuration

javascript

module.exports = {
  types: [
    { type: 'feat', section: '新功能' },
    { type: 'fix', section: '缺陷修复' },
    { type: 'perf', section: '性能优化' },
    { type: 'refactor', section: '代码重构' },
    { type: 'docs', section: '文档更新' },
    { type: 'test', section: '测试' },
    { type: 'chore', section: '构建/工具', hidden: true },
    { type: 'ci', section: '持续集成', hidden: true },
    { type: 'style', section: '代码格式', hidden: true }
  ],
  commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
  compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'
}

javascript

module.exports = {
  types: [
    { type: 'feat', section: 'New Features' },
    { type: 'fix', section: 'Bug Fixes' },
    { type: 'perf', section: 'Performance Optimizations' },
    { type: 'refactor', section: 'Code Refactoring' },
    { type: 'docs', section: 'Documentation Updates' },
    { type: 'test', section: 'Testing' },
    { type: 'chore', section: 'Build/Tools', hidden: true },
    { type: 'ci', section: 'Continuous Integration', hidden: true },
    { type: 'style', section: 'Code Formatting', hidden: true }
  ],
  commitUrlFormat: '{{host}}/{{owner}}/{{repository}}/commit/{{hash}}',
  compareUrlFormat: '{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'
}

8. commitlint 中文配置

8. commitlint Chinese Configuration

安装

Installation

bash

npm install -D @commitlint/cli @commitlint/config-conventional

bash

npm install -D @commitlint/cli @commitlint/config-conventional

commitlint.config.js

javascript

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'revert'
    ]],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-empty': [2, 'never'],
    'subject-max-length': [2, 'always', 100],
    // 允许中文字符，关闭 subject-case 限制
    'subject-case': [0],
    // 关闭 header-max-length 或放宽（中文占宽较大）
    'header-max-length': [2, 'always', 120],
    'body-max-line-length': [1, 'always', 200],
    'footer-max-line-length': [1, 'always', 200]
  },
  prompt: {
    messages: {
      type: '选择提交类型:',
      scope: '输入影响范围（可选）:',
      subject: '填写简短描述:',
      body: '填写详细描述（可选，使用 "|" 换行）:',
      breaking: '列出不兼容变更（可选）:',
      footer: '关联的 Issue（可选，例如 #123）:',
      confirmCommit: '确认提交以上信息？'
    }
  }
}

javascript

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'revert'
    ]],
    'type-case': [2, 'always', 'lower-case'],
    'type-empty': [2, 'never'],
    'subject-empty': [2, 'never'],
    'subject-max-length': [2, 'always', 100],
    // Allow Chinese characters, disable subject-case restriction
    'subject-case': [0],
    // Disable or relax header-max-length (Chinese characters take more width)
    'header-max-length': [2, 'always', 120],
    'body-max-line-length': [1, 'always', 200],
    'footer-max-line-length': [1, 'always', 200]
  },
  prompt: {
    messages: {
      type: 'Select commit type:',
      scope: 'Enter affected scope (optional):',
      subject: 'Enter brief description:',
      body: 'Enter detailed description (optional, use "|" for line breaks):',
      breaking: 'List incompatible changes (optional):',
      footer: 'Associated Issues (optional, e.g., #123):',
      confirmCommit: 'Confirm the above commit information?'
    }
  }
}

9. husky + lint-staged 集成

9. husky + lint-staged Integration

安装与初始化

Installation and Initialization

bash

npm install -D husky lint-staged
npx husky init

bash

npm install -D husky lint-staged
npx husky init

配置 commit-msg 钩子

Configure commit-msg Hook

bash

undefined

bash

undefined

.husky/commit-msg

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

undefined

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

undefined

配置 pre-commit 钩子

Configure pre-commit Hook

bash

undefined

bash

undefined

.husky/pre-commit

npx lint-staged

undefined

npx lint-staged

undefined

lint-staged 配置（package.json）

lint-staged Configuration (package.json)

json

{
  "lint-staged": {
    "*.{js,ts,jsx,tsx,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,less}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}

json

{
  "lint-staged": {
    "*.{js,ts,jsx,tsx,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,less}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}

交互式提交（可选）

Interactive Commit (Optional)

bash

npm install -D commitizen cz-conventional-changelog

bash

npm install -D commitizen cz-conventional-changelog

package.json 中添加

Add to package.json

{ "config": { "commitizen": { "path": "cz-conventional-changelog" } }, "scripts": { "commit": "cz" } }


运行 `npm run commit` 即可进入交互式提交引导。

{ "config": { "commitizen": { "path": "cz-conventional-changelog" } }, "scripts": { "commit": "cz" } }


Run `npm run commit` to enter interactive commit guidance.

10. 团队规范检查清单

10. Team Specification Checklist

提交前自查

Pre-Commit Self-Check

type 是否正确选择（feat/fix/docs/...）
scope 是否准确描述了影响模块
subject 是否为动宾短语且不超过 50 字符
subject 末尾是否去掉了句号
body 是否说明了变更原因和方案
不兼容变更是否标注了 BREAKING CHANGE
相关 Issue 是否已关联
一次提交是否只做了一件事（原子性）

Is the
```
type
```
correctly selected (feat/fix/docs/...)
Does the
```
scope
```
accurately describe the affected module
Is the
```
subject
```
a verb-object phrase and no more than 50 characters
Is there no period at the end of the
```
subject
```
Does the
```
body
```
explain the change reason and solution
Are incompatible changes marked with BREAKING CHANGE
Are related Issues associated
Does one commit only do one thing (atomicity)

团队落地步骤

Team Implementation Steps

工具链配置：按上述步骤配置 commitlint + husky，让规范可执行
模板共享：将
```
.commitlintrc
```
、
```
.husky/
```
等配置提交到仓库
团队培训：组织 15 分钟的规范说明会，演示工具使用
Code Review：Review 时关注 commit message 质量
持续迭代：每季度回顾规范执行情况，根据团队反馈调整

Toolchain Configuration: Configure commitlint + husky as per the above steps to make the specification enforceable
Template Sharing: Commit configurations like
```
.commitlintrc
```
,
```
.husky/
```
to the repository
Team Training: Organize a 15-minute specification briefing to demonstrate tool usage
Code Review: Focus on commit message quality during reviews
Continuous Iteration: Review specification implementation quarterly and adjust based on team feedback

常见问题

Frequently Asked Questions

Q: 中英文混排时空格怎么处理？ A: 中文与英文/数字之间加一个空格，如「添加 Redis 缓存」。

Q: scope 用中文还是英文？ A: 团队内统一即可。推荐中文（可读性好），但需在 commitlint 中关闭 scope-case 检查。

Q: 多人协作时如何保证规范一致？ A: 靠工具而非靠自觉。配置好 husky + commitlint，不符合规范的提交会被拦截。

Q: How to handle spaces when mixing Chinese and English? A: Add a space between Chinese and English/numbers, e.g., "Add Redis cache".

Q: Should
scope
be in Chinese or English? A: Just keep it consistent within the team. Chinese is recommended (better readability), but you need to disable the scope-case check in commitlint.

Q: How to ensure consistent specifications during collaborative work? A: Rely on tools rather than self-discipline. Configure husky + commitlint properly, and commits that don't meet the specifications will be blocked.