---
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)
