README.md



Git Hooks 文档


📋 概述

本项目使用 Husky 管理 Git hooks，实现代码质量检查和自动化 CHANGELOG 更新。


🔧 可用的 Hooks


1. commit-msg - Commit Message 格式验证

文件：.husky/commit-msg

功能：验证 commit message 是否符合 Conventional Commits 格式规范。

格式要求：

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


允许的类型：


feat - 新功能

fix - Bug 修复

docs - 文档更新

style - 代码格式（不影响功能）

refactor - 重构（不是新功能也不是修复）

perf - 性能优化

test - 测试相关

chore - 构建/工具链相关

revert - 回滚提交


允许的范围：


material - 资料/文档模块

product - 产品模块

plan - 计划书模块

user - 用户模块

auth - 认证模块

api - API 接口

ui - UI 组件

config - 配置文件

build - 构建相关

ci - CI/CD 相关

release - 发布相关

husky - Git Hooks 相关

chore - 其他杂项

to-parse - 文档解析相关


主题要求：


简短描述（不超过 50 字符）
使用中文
不以句号结尾
使用祈使句（如 "添加" 而非 "添加了"）


示例：

feat(material): 添加文档列表分类导航

fix(auth): 修复登录状态判断问题

docs(readme): 更新项目说明文档


2. pre-commit - 提交前检查和 CHANGELOG 更新

文件：.husky/pre-commit

功能：


ESLint 代码格式检查
检查调试代码（console.log、debugger）
改动规模检查（提示代码审查）

自动更新 CHANGELOG.md（在提交前，包含在当前提交中）


CHANGELOG 更新规则：


只对以下类型更新：feat、fix、refactor、perf

跳过：docs(changelog) 类型的提交（避免循环）
CHANGELOG 变更会包含在当前提交中


3. post-commit - 提交后处理

文件：.husky/post-commit

功能：


显示提交成功信息和改动统计

补充 CHANGELOG 中的 commit hash（使用 amend）


工作流程：

git commit
  ↓
[pre-commit hook] 代码检查 + 更新 CHANGELOG
  ↓
[commit-msg hook] 验证 commit message 格式
  ↓
创建提交（包含 CHANGELOG 变更）
  ↓
[post-commit hook] ✅ 执行
  ├─ 显示提交信息
  └─ 补充 CHANGELOG 中的 commit hash（amend）


CHANGELOG 更新流程：


Pre-commit 阶段：


检查 commit message 类型
如果符合条件，调用 scripts/changelog/update-changelog-precommit.sh

生成 CHANGELOG 条目（commit hash 暂时为 "pending"）
将 CHANGELOG 加入暂存区


Post-commit 阶段：


检查 CHANGELOG 中是否有 "pending" hash
如果有，替换为真实的 commit hash
使用 git commit --amend --no-edit 更新提交


优势：


✅ CHANGELOG 和功能变更在同一个提交中
✅ 不会产生额外的提交
✅ 不会触发无限循环


输出示例：

🔍 开始 Pre-commit 检查...

📋 步骤 1/3: 代码格式检查
  ✅ ESLint 检查通过

📋 步骤 2/3: 检查调试代码
  ✅ 调试代码检查通过

📋 步骤 3/3: 改动规模检查
  ✅ 改动规模检查通过

📋 步骤 4/4: 更新 CHANGELOG
  ✅ CHANGELOG.md 已自动更新并加入暂存区
     类型: 新增
     范围: search
     描述: 搜索 Tab 显示结果数量

✅ 所有检查通过！
🚀 开始提交...

📝 提交信息：
   Hash:   f059121
   Author: huyirui
   Date:   2026-02-28 20:07:50
   Msg:    refactor(search): 搜索 Tab 显示结果数量

📊 改动统计：
   文件数:     2
   新增行数:   +37
   删除行数:   -5

  ✅ CHANGELOG commit hash 已更新


⚙️ 配置说明


安装

# Husky 已自动配置
# Hooks 位于 .husky/ 目录

# 确保 hooks 可执行
chmod +x .husky/*


自定义

如需修改 hook 行为，直接编辑 .husky/ 目录下的脚本文件。


📝 Commit Message 最佳实践


✅ 推荐格式

feat(module): 简短描述

- 具体变更点 1
- 具体变更点 2
- 具体变更点 3

Closes #123


❌ 避免格式

# ❌ 太长
feat(module): 这是一个非常长的描述，超过五十个字符的限制，应该避免这种写法

# ❌ 句号结尾
feat(module): 添加新功能。

# ❌ 非祈使句
feat(module): 添加了新功能


🔍 故障排查


问题：提交被拒绝

原因：commit message 格式不符合规范

解决：按照 <type>(<scope>): <subject> 格式重新编写


问题：CHANGELOG 未更新

可能原因：


Commit message 类型不符合要求（只有 feat/fix/refactor/perf 会更新）

scripts/changelog/update-changelog-precommit.sh 脚本路径错误

CHANGELOG.md 文件不存在
Commit message 格式不正确


解决：


检查 commit message 类型是否为 feat、fix、refactor 或 perf

确认脚本存在且可执行：chmod +x scripts/changelog/update-changelog-precommit.sh

运行 pnpm lint 确保没有语法错误


问题：CHANGELOG 更新导致无限循环

已解决：新版本使用 pre-commit 阶段更新，包含在当前提交中，不会产生额外提交。

如果仍然遇到循环：


检查 post-commit hook 是否正确
确认跳过了 docs(changelog) 类型的提交
检查 pre-commit hook 中的类型判断逻辑


📚 相关文档


CHANGELOG 工具文档
项目 CHANGELOG
Commit Message 规范