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. post-commit - 提交后自动化

文件：.husky/post-commit

功能：


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

自动更新 CHANGELOG.md（通过 scripts/changelog/update-changelog.sh）
创建补充提交（如果 CHANGELOG 有变更）


工作流程：

git commit
  ↓
[pre-commit hook] 代码质量检查
  ↓
[commit-msg hook] 验证 commit message 格式
  ↓
[post-commit hook] ✅ 执行
  ├─ 显示提交信息
  ├─ 自动更新 CHANGELOG
  └─ 如有变更，创建补充提交


CHANGELOG 自动更新流程：


解析最新的 commit message
生成对应的 CHANGELOG 条目
插入到 docs/CHANGELOG.md 开头
如果 CHANGELOG 有变更：


暂存 CHANGELOG 文件
创建补充提交：docs(changelog): 更新 CHANGELOG - <原始提交主题>

补充提交使用 --no-verify 跳过 hooks，避免循环


输出示例：

✅ 提交成功！

📝 提交信息：
   Hash:   a6618ea
   Author: huyirui
   Date:   2026-02-22 15:30:45
   Msg:    fix(husky): 修复 CHANGELOG 自动更新功能

📊 改动统计：
   文件数:     3
   新增行数:   +45
   删除行数:   -12

📝 更新 CHANGELOG.md...
  ✅ CHANGELOG.md 已自动更新
     类型: 修复
     范围: husky
     描述: 修复 CHANGELOG 自动更新功能

  ✅ CHANGELOG 补充提交已创建


⚙️ 配置说明


安装

# 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 格式不正确

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

docs/CHANGELOG.md 文件不存在


解决：


检查 commit message 格式
运行 pnpm changelog:check 检查漏记
手动运行脚本调试


📚 相关文档


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