Husky项目中pre-commit钩子执行失败的排查与解决

在基于Husky的项目开发过程中，pre-commit钩子执行失败是一个常见问题。本文将通过一个实际案例，分析导致该问题的原因以及相应的解决方案。

问题现象

开发者在执行git commit命令时，系统报错"unknown revision or path not in the working tree"，导致提交失败。错误信息显示pre-commit钩子以错误代码1退出。该问题同时出现在终端命令行和VSCode的Git扩展中。

环境配置

项目环境为：

• 使用Husky 9.0.11版本
• 基于Nx的Monorepo项目结构
• Node.js v20.10.0环境
• npm 10.4.0包管理器
• 运行在Linux系统上

问题分析

经过深入排查，发现导致该问题的原因主要有两个：

1. 未定义的环境变量引用
   在pre-commit钩子脚本中，开发者引用了一个未定义的环境变量$DICTIONARY。这种未定义的变量引用会导致脚本执行异常。

2. 错误的ESLint配置文件路径
   在项目的lint-staged配置中，虽然配置了移除被忽略文件的选项，但在其中一个子包的.eslintrc.json文件中，extends配置指向了错误的路径。具体表现为：

   • 实际需要的路径是"../../.eslintrc.json"
   • 但配置中写成了"../.eslintrc.json"

解决方案

针对上述问题，采取以下解决措施：

1. 修正环境变量引用
   检查并确保所有在pre-commit钩子中引用的环境变量都已正确定义。如果某些变量不再需要，应该从脚本中移除。

2. 修复ESLint配置路径
   在Monorepo项目中，由于包结构的嵌套关系，需要特别注意配置文件的相对路径引用。将错误的路径引用更正为：

   "extends": ["../../.eslintrc.json"]
   

经验总结

通过这个案例，我们可以得出以下开发经验：

1. 严格检查脚本中的变量引用
   在编写任何脚本时，都应该确保所有引用的变量都已正确定义。可以使用set -u等选项来帮助发现未定义的变量引用。

2. 注意Monorepo中的路径问题
   在Monorepo项目中，由于文件结构的复杂性，配置文件的路径引用容易出错。建议：

   • 使用绝对路径或项目根目录的相对路径
   • 建立统一的路径引用规范
   • 在重构后全面检查配置文件的路径引用

3. 善用调试工具
   当遇到类似问题时，可以：

   • 单独运行pre-commit脚本以获取更详细的错误信息
   • 使用echo或console.log输出中间变量值
   • 逐步执行脚本定位具体出错位置

通过系统性地排查和解决这类问题，可以显著提高开发效率和代码质量。