Husky 钩子执行时 Zsh 报错问题分析与解决

在使用 Husky 进行 Git 钩子管理时，部分开发者遇到了 Zsh 环境下的报错问题。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

开发者在 iTerm2 终端（Zsh 环境）中执行 Git 提交操作时，Husky 的 pre-commit 钩子触发了以下异常：

1. Zsh 提示 "bad substitution" 错误
2. 报错显示无法加载 Oh My Zsh
3. 出现 "command not found" 等提示

根本原因

经过排查发现，问题源于 Husky 的初始化脚本中错误地加载了 Zsh 配置文件。具体表现为：

1. 在 ~/.config/husky/init.sh 文件中存在 . ~/.zshrc 语句
2. 当 Husky 通过 sh 执行钩子时，Zsh 特有的语法无法被正确解析

解决方案

方法一：清理初始化配置

1. 打开 ~/.config/husky/init.sh 文件
2. 移除或注释掉 . ~/.zshrc 语句
3. 保存文件后测试 Git 提交操作

方法二：正确配置 Node 版本管理

对于使用 nvm 等 Node 版本管理工具的用户：

1. 确保在 Husky 初始化脚本中只包含必要的环境变量设置
2. 避免直接加载完整的 Zsh 配置文件
3. 推荐使用 nvm 的 --no-use 参数来避免环境冲突

技术原理

Husky 默认通过 sh 执行 Git 钩子，而 Zsh 的配置文件包含大量 shell 特有的语法和功能。当 sh 尝试解析 Zsh 配置文件时，会导致：

1. Zsh 特有的语法（如 ${(%):-%n}）无法被识别
2. Zsh 的扩展命令（如 compctl）在 sh 中不存在
3. 环境初始化过程出现连锁错误

最佳实践

1. 保持 Husky 初始化脚本的简洁性
2. 在钩子脚本中显式声明需要的环境变量
3. 避免在 Husky 配置中加载完整的 shell 配置文件
4. 对于复杂的初始化需求，建议使用专门的脚本文件并通过绝对路径调用

总结

通过理解 Husky 的工作机制和 shell 环境差异，开发者可以避免这类环境配置问题。关键在于保持初始化过程的精简和明确，确保在不同 shell 环境下的兼容性。对于使用 Zsh 的开发者，特别需要注意避免将 Zsh 特有的配置混入通用脚本中。