pre-commit钩子不能可靠生成文档，应改用pre-push钩子；pre-push时提交已落库、分支状态确定，可安全执行文档生成与自动提交，但需禁用钩子防止循环，并在ci中复现相同逻辑且配置写权限。
pre-commit钩子能拦截提交但不能自动生成文档
Git的pre-commit钩子在代码暂存后、提交前触发，它能看到git diff --cached的变更，但此时工作区和暂存区都尚未写入对象数据库，无法可靠读取完整项目状态（比如依赖未安装、构建产物缺失）。多数文档生成工具（如Swagger、Typedoc、Sphinx）需要运行时环境或源码解析，直接塞进pre-commit容易失败或生成过期内容。
推荐用pre-push钩子触发文档构建与推送
真正可靠的时机是pre-push：此时提交已落库，分支状态确定，且能明确知道目标远程分支（比如推送到origin/main）。文档生成可基于当前HEAD执行，失败时还能阻断推送，避免发布不一致版本。
- 钩子脚本需检查
git rev-parse --abbrev-ref --symbolic-full-name @{u}确认是否推往主干分支 - 生成命令建议加超时和错误捕获，例如：
npx typedoc --out docs/ src/ || exit 1 - 生成后必须
git add docs/并git commit --no-edit -a，否则后续推送会因本地未同步被拒绝 - 注意排除
docs/目录在.gitignore中——如果忽略，git add无效；如果不忽略，需确保CI不重复生成
文档生成后如何自动提交又不引发无限循环
pre-push里执行git commit会导致二次触发钩子，必须禁用。标准做法是在提交命令中加环境变量开关：
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
if [ "$SKIP_HOOKS" != "1" ]; then SKIP_HOOKS=1 git commit -m "docs: auto-generated from $(git rev-parse HEAD)" -a --no-verify fi
这样下次pre-push执行时，git commit跳过所有钩子，避免死循环。同时要确保--no-verify只作用于该次提交，不影响人工操作。
CI流程里必须复现相同逻辑，否则文档会丢失
本地pre-push生成的文档只存在于你本地仓库，若CI从远程拉取代码再构建，它根本看不到你本地提交的docs/。所以CI配置（如GitHub Actions的.github/workflows/docs.yml）必须包含完全相同的生成、提交、推送步骤，并使用actions/checkout@v4的token权限允许推送回分支。
最容易漏掉的是权限配置——GitHub默认禁止Workflow推送回仓库，需显式开启permissions: contents: write，否则CI跑完就静默失败。
