husky Git 钩子疑难排错实战【免费下载链接】huskyGit hooks made easy woof!项目地址: https://gitcode.com/gh_mirrors/hu/husky跑git commit弹出husky - command not found in PATH...或钩子文件明明存在、提交却原样通过——这是 husky 排错里最高频的两类报错。本文不罗列问题而是给一条诊断主线基线检查 → 按core.hooksPath输出分叉 → 修复 → 回归验证每步命令可直接复制执行。 基线检查Git 版本、.git 与 hooksPath 三条命令husky 9.x 不修改.git/hooks/下任何文件安装时只执行一条git config core.hooksPath .husky/_把钩子目录整体重定向到.husky/_见 index.js。所以一切排错都从这条配置读起。先跑git --version如果输出低于 2.9 →core.hooksPath是 Git 2.9 起才支持的配置项docs/troubleshoot.md钩子永远不会生效先升级 Git后面所有步骤都不必再看。先跑ls -a如果输出里没有.git→ 你不在 Git 仓库根目录安装逻辑会直接返回.git cant be foundindex.js回到含.git的目录再继续。先跑git config core.hooksPath运行git config core.hooksPath把输出记下来下一站按它分叉。环境干净的判定标准Git ≥ 2.9、.git存在、输出为.husky/_。官方测试正是用这条断言验证安装结果见 test/functions.sh 中的expect_hooksPath_to_be .husky/_。第一分叉按 hooksPath 输出选择诊断方向把上一条命令的输出对照下表两个分支互斥git config core.hooksPath输出判断走向空从未安装、被HUSKY0跳过、或配置被其他工具覆盖分支①重装指向已删除的旧目录卸载残留Git 把钩子重定向到不存在的路径分支①清除残留.husky/_安装正常问题在钩子运行时分支②查运行时分支①hooksPath 为空或指向别处怎么重置安装输出报错三种文案对应三种环境先跑npx husky安装脚本的返回值本身就指明卡点index.js输出git command not found→ 执行安装的终端里没有 git。先跑command -v git无输出 → 安装 Git 或把其路径加入 PATH。test/5_git_command_not_found.sh 用process.env.PATH 复现的正是这条分支输出.git cant be found→ 当前不在仓库根目录回到含.git的目录重跑输出HUSKY0 skip install→ 环境变量里带着HUSKY0。运行unset HUSKY后重跑安装原理一句话安装 一条git config加一组写进.husky/_/的文件三者缺一core.hooksPath就不会被写入。卸载后 .git/hooks/ 不工作清除 hooksPath 残留现象删掉 husky 依赖后手工放在.git/hooks/里的钩子也不再执行。原因卸载不会清理 Git 仓库配置core.hooksPath仍指向已删除的.husky/_Git 于是把钩子目录整体重定向到一个不存在的路径docs/troubleshoot.md。修复git config --unset core.hooksPath预期再运行git config core.hooksPath无输出Git 回到默认行为使用.git/hooks/。怀疑有全局残留时加--global前缀查看一次。分支②hooksPath 正确钩子静默失效的两种原因先建立心智模型每次提交真正执行的是统一运行时脚本.husky/_/h即仓库根目录的 husky 脚本它先 source 初始化文件、检查HUSKY、把node_modules/.bin注入 PATH最后才以sh -e跑你的钩子。排查顺序因此是环境变量 → 文件名。HUSKY0 静默禁用检查 init.sh运行时脚本在 source 完初始化文件之后、执行钩子之前有一行判断husky[ ${HUSKY-} 0 ] exit 0初始化文件是~/.config/husky/init.shWindows 为C:\Users\你的用户名\.config\husky\init.sh。如果你曾为全局禁用或 CI 在其中写过export HUSKY0钩子会静默跳过、提交照常成功——表现为钩子配好了却没跑。先跑echo $HUSKY cat ~/.config/husky/init.sh任一输出含HUSKY0→ 删掉 init.sh 中该行或临时unset HUSKY长期禁用请从 init.sh 移除test/9_husky_0.sh 验证了这条分支在 init.sh 写入export HUSKY0后带exit 1钩子的git commit依然以 0 退出顺带一提如果终端出现husky - ~/.huskyrc is DEPRECATED, please move your code to ~/.config/husky/init.sh说明旧版~/.huskyrc还在按提示迁移到 init.sh 即可。钩子文件名不合法对照标准清单Git 只执行文件名恰好匹配标准钩子名的文件precommit缺连字符和pre-commit.sh带扩展名都会被直接忽略docs/troubleshoot.md。先跑ls .husky/任何文件名不在标准清单内 → 改名为标准名称并去掉扩展名husky 安装时默认生成 14 个转发文件pre-commit、commit-msg、post-commit、pre-push等完整清单见 index.jscommand not found 与 Windows tty 报错的专项修复走到这里说明钩子确实在执行报错出在脚本内部。报错 command not found in PATHGUI 客户端 版本管理器husky - command not found in PATH...只在钩子脚本以退出码 127 结束时打印husky。典型现象终端里一切正常IDE 或 Git GUI 客户端里报node: command not found。原因版本管理器nvm、fnm、volta 等靠 shell 启动文件把 Node 目录注入 PATH而 GUI 启动的应用不经过启动文件PATH 里没有 Node 安装路径docs/how-to.md。修复husky 运行时会先 source~/.config/husky/init.sh再跑钩子把版本管理器的初始化代码复制进去# ~/.config/husky/init.sh export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh如果你的.zshrc足够轻量也可以直接写. ~/.zshrc。钩子里调用的命令不在 node_modules/.bin运行时脚本已执行export PATHnode_modules/.bin:$PATHhusky钩子可以直接写eslint这类局部安装的命令test/7_node_modules_path.sh 断言钩子内 PATH 必含node_modules/.bin。仍是 127 → 确认该命令真的在依赖里、node_modules已安装必要时改用npm run script间接调用Windows Yarn 报 stdin is not a ttyGit Bash 下钩子环境没有交互式 ttyYarn 的交互命令会检测失败docs/troubleshoot.md。修复创建.husky/common.shcommand_exists () { command -v $1 /dev/null 21 } # Workaround for Windows 10, Git Bash, and Yarn if command_exists winpty test -t 1; then exec /dev/tty fi在每条执行 yarn 的钩子顶部 source 它# .husky/pre-commit . .husky/common.sh yarn ...原理有winpty且 stdout 是终端时把 stdin 重定向到/dev/ttyyarn 就能拿到真终端。回归验证用一条必失败钩子确认链路仓库自己的测试test/6_command_not_found.sh就是标准做法——写一条必失败的钩子验证调用链连通echo exit 127 .husky/pre-commit git commit -m foo预期输出提交被拦截终端出现husky - command not found in PATH...。看到它 → 链路正常问题只可能在你的钩子脚本内容里完全没反应 → 回到分支①重新确认 hooksPath。再换成成功场景收尾echo echo $PATH | grep node_modules/.bin .husky/pre-commit git commit -m foo提交成功 → PATH 注入正常。最后确认一次配置git config core.hooksPath输出.husky/_即为最终态。记住口诀先看 Git 2.9再读 hooksPath——空则重装对则查HUSKY0最后用一条必失败钩子验链路。【免费下载链接】huskyGit hooks made easy woof!项目地址: https://gitcode.com/gh_mirrors/hu/husky创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/27 9:31:01 · 阅读 1.2k husky Git 钩子疑难排错实战
husky Git 钩子疑难排错实战【免费下载链接】huskyGit hooks made easy woof!项目地址: https://gitcode.com/gh_mirrors/hu/husky跑git commit弹出husky - command not found in PATH...或钩子文件明明存在、提交却原样通过——这是 husky 排错里最高频的两类报错。本文不罗列问题而是给一条诊断主线基线检查 → 按core.hooksPath输出分叉 → 修复 → 回归验证每步命令可直接复制执行。 基线检查Git 版本、.git 与 hooksPath 三条命令husky 9.x 不修改.git/hooks/下任何文件安装时只执行一条git config core.hooksPath .husky/_把钩子目录整体重定向到.husky/_见 index.js。所以一切排错都从这条配置读起。先跑git --version如果输出低于 2.9 →core.hooksPath是 Git 2.9 起才支持的配置项docs/troubleshoot.md钩子永远不会生效先升级 Git后面所有步骤都不必再看。先跑ls -a如果输出里没有.git→ 你不在 Git 仓库根目录安装逻辑会直接返回.git cant be foundindex.js回到含.git的目录再继续。先跑git config core.hooksPath运行git config core.hooksPath把输出记下来下一站按它分叉。环境干净的判定标准Git ≥ 2.9、.git存在、输出为.husky/_。官方测试正是用这条断言验证安装结果见 test/functions.sh 中的expect_hooksPath_to_be .husky/_。第一分叉按 hooksPath 输出选择诊断方向把上一条命令的输出对照下表两个分支互斥git config core.hooksPath输出判断走向空从未安装、被HUSKY0跳过、或配置被其他工具覆盖分支①重装指向已删除的旧目录卸载残留Git 把钩子重定向到不存在的路径分支①清除残留.husky/_安装正常问题在钩子运行时分支②查运行时分支①hooksPath 为空或指向别处怎么重置安装输出报错三种文案对应三种环境先跑npx husky安装脚本的返回值本身就指明卡点index.js输出git command not found→ 执行安装的终端里没有 git。先跑command -v git无输出 → 安装 Git 或把其路径加入 PATH。test/5_git_command_not_found.sh 用process.env.PATH 复现的正是这条分支输出.git cant be found→ 当前不在仓库根目录回到含.git的目录重跑输出HUSKY0 skip install→ 环境变量里带着HUSKY0。运行unset HUSKY后重跑安装原理一句话安装 一条git config加一组写进.husky/_/的文件三者缺一core.hooksPath就不会被写入。卸载后 .git/hooks/ 不工作清除 hooksPath 残留现象删掉 husky 依赖后手工放在.git/hooks/里的钩子也不再执行。原因卸载不会清理 Git 仓库配置core.hooksPath仍指向已删除的.husky/_Git 于是把钩子目录整体重定向到一个不存在的路径docs/troubleshoot.md。修复git config --unset core.hooksPath预期再运行git config core.hooksPath无输出Git 回到默认行为使用.git/hooks/。怀疑有全局残留时加--global前缀查看一次。分支②hooksPath 正确钩子静默失效的两种原因先建立心智模型每次提交真正执行的是统一运行时脚本.husky/_/h即仓库根目录的 husky 脚本它先 source 初始化文件、检查HUSKY、把node_modules/.bin注入 PATH最后才以sh -e跑你的钩子。排查顺序因此是环境变量 → 文件名。HUSKY0 静默禁用检查 init.sh运行时脚本在 source 完初始化文件之后、执行钩子之前有一行判断husky[ ${HUSKY-} 0 ] exit 0初始化文件是~/.config/husky/init.shWindows 为C:\Users\你的用户名\.config\husky\init.sh。如果你曾为全局禁用或 CI 在其中写过export HUSKY0钩子会静默跳过、提交照常成功——表现为钩子配好了却没跑。先跑echo $HUSKY cat ~/.config/husky/init.sh任一输出含HUSKY0→ 删掉 init.sh 中该行或临时unset HUSKY长期禁用请从 init.sh 移除test/9_husky_0.sh 验证了这条分支在 init.sh 写入export HUSKY0后带exit 1钩子的git commit依然以 0 退出顺带一提如果终端出现husky - ~/.huskyrc is DEPRECATED, please move your code to ~/.config/husky/init.sh说明旧版~/.huskyrc还在按提示迁移到 init.sh 即可。钩子文件名不合法对照标准清单Git 只执行文件名恰好匹配标准钩子名的文件precommit缺连字符和pre-commit.sh带扩展名都会被直接忽略docs/troubleshoot.md。先跑ls .husky/任何文件名不在标准清单内 → 改名为标准名称并去掉扩展名husky 安装时默认生成 14 个转发文件pre-commit、commit-msg、post-commit、pre-push等完整清单见 index.jscommand not found 与 Windows tty 报错的专项修复走到这里说明钩子确实在执行报错出在脚本内部。报错 command not found in PATHGUI 客户端 版本管理器husky - command not found in PATH...只在钩子脚本以退出码 127 结束时打印husky。典型现象终端里一切正常IDE 或 Git GUI 客户端里报node: command not found。原因版本管理器nvm、fnm、volta 等靠 shell 启动文件把 Node 目录注入 PATH而 GUI 启动的应用不经过启动文件PATH 里没有 Node 安装路径docs/how-to.md。修复husky 运行时会先 source~/.config/husky/init.sh再跑钩子把版本管理器的初始化代码复制进去# ~/.config/husky/init.sh export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh如果你的.zshrc足够轻量也可以直接写. ~/.zshrc。钩子里调用的命令不在 node_modules/.bin运行时脚本已执行export PATHnode_modules/.bin:$PATHhusky钩子可以直接写eslint这类局部安装的命令test/7_node_modules_path.sh 断言钩子内 PATH 必含node_modules/.bin。仍是 127 → 确认该命令真的在依赖里、node_modules已安装必要时改用npm run script间接调用Windows Yarn 报 stdin is not a ttyGit Bash 下钩子环境没有交互式 ttyYarn 的交互命令会检测失败docs/troubleshoot.md。修复创建.husky/common.shcommand_exists () { command -v $1 /dev/null 21 } # Workaround for Windows 10, Git Bash, and Yarn if command_exists winpty test -t 1; then exec /dev/tty fi在每条执行 yarn 的钩子顶部 source 它# .husky/pre-commit . .husky/common.sh yarn ...原理有winpty且 stdout 是终端时把 stdin 重定向到/dev/ttyyarn 就能拿到真终端。回归验证用一条必失败钩子确认链路仓库自己的测试test/6_command_not_found.sh就是标准做法——写一条必失败的钩子验证调用链连通echo exit 127 .husky/pre-commit git commit -m foo预期输出提交被拦截终端出现husky - command not found in PATH...。看到它 → 链路正常问题只可能在你的钩子脚本内容里完全没反应 → 回到分支①重新确认 hooksPath。再换成成功场景收尾echo echo $PATH | grep node_modules/.bin .husky/pre-commit git commit -m foo提交成功 → PATH 注入正常。最后确认一次配置git config core.hooksPath输出.husky/_即为最终态。记住口诀先看 Git 2.9再读 hooksPath——空则重装对则查HUSKY0最后用一条必失败钩子验链路。【免费下载链接】huskyGit hooks made easy woof!项目地址: https://gitcode.com/gh_mirrors/hu/husky创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考