---
source: ../../../../options/commit-message/traditional-chinese.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2025-12-30
status: current
---

# 繁体中文 Commit 讯息

> **语言**: [English](../../../../options/commit-message/traditional-chinese.md) | 繁体中文

**上层标准**: [Commit 讯息指南](../../../../core/commit-message-guide.md)

---

## 概述

本选项定义以繁体中文撰写 commit 讯息的标准。适合以中文为主要沟通语言的团队，让 commit 历史更容易阅读和理解。

## 适用情境

- 台湾或香港的开发团队
- 内部专案（非开源）
- 中文为主要语言的组织
- 需要非技术人员阅读 commit 历史的专案

## 格式

### 基本结构

```
<类型>(<范围>): <主题>

<内文>

<页尾>
```

### 组成元素

| 元素 | 必填 | 说明 |
|------|------|------|
| 类型 | 是 | 变更类别（feat、fix、docs 等）|
| 范围 | 否 | 影响的模组或元件 |
| 主题 | 是 | 简短描述 |
| 内文 | 否 | 详细说明 |
| 页尾 | 否 | 参考连结、重大变更 |

## Commit 类型

| 类型 | 中文说明 | 范例 |
|------|----------|------|
| `feat` | 新功能 | `feat: 新增使用者验证功能` |
| `fix` | 错误修复 | `fix: 修正登入逾时问题` |
| `docs` | 文件更新 | `docs: 更新 API 参考文件` |
| `style` | 格式调整 | `style: 修正工具模组缩排` |
| `refactor` | 程式码重构 | `refactor: 简化验证逻辑` |
| `perf` | 效能优化 | `perf: 优化资料库查询` |
| `test` | 测试相关 | `test: 新增验证模组单元测试` |
| `chore` | 维护作业 | `chore: 更新相依套件` |

## 撰写指南

### 主题行

1. **使用动词开头**：「新增功能」而非「功能新增」
2. **保持简洁**：50 字元以内
3. **不加句号**：「新增功能」而非「新增功能。」
4. **具体明确**：「修正使用者服务空指标问题」而非「修正错误」

### 内文

1. **每行 72 字元**：保持终端机可读性
2. **说明原因**：解释为什么要做这个变更
3. **使用列表**：多项变更时使用项目符号
4. **空行分隔**：与主题行以空行分隔

## 范例

### 简单功能

```
feat(auth): 新增密码强度指示器

- 在密码输入时显示强度条
- 输入时显示密码要求
- 阻止提交弱密码

关闭 #234
```

### 错误修复

```
fix(api): 处理付款闸道的空值回应

付款闸道在服务降级时偶尔会回传 null 而非错误物件，
这导致结帐流程出现未处理的例外。

新增空值检查和适当的错误处理，优雅地处理此边缘案例。

修复 #567
```

### 重大变更

```
feat(api): 将验证改为 JWT 权杖

重大变更：移除基于 Session 的验证。
所有 API 客户端必须使用 JWT 权杖进行验证。

迁移指南：
1. 从 /auth/token 端点取得 JWT 权杖
2. 在 Authorization 标头中包含权杖
3. 移除 session cookie 处理

关闭 #789
```

## 反面教材

### 不良范例

```
# 太笼统
fix: 修正错误

# 没有说明
更新使用者服务

# 无意义
进行中
杂项变更
```

### 改善范例

```
# 具体明确
fix(auth): 防止档案上传期间 session 逾时

# 简洁并在内文补充细节
feat(users): 新增个人头像上传功能

支援 JPEG、PNG 和 WebP 格式。
图片自动调整为 100x100、200x200 和 400x400 像素。
```

## 相关选项

- [英文](./english.md) - 英文 Commit 讯息
- [双语](./bilingual.md) - 中英双语格式

---

## 授权条款

本文件采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权条款。

**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
