Husky 命令未找到的解决方案

问题描述

当在 Node.js 项目中配置了 Husky 并运行 npm install 时，可能会遇到 sh: husky: command not found 错误：

noa-be@1.0.0 prepare
husky install

sh: husky: command not found
npm ERR! code 127

这个错误通常发生在项目配置如下时：

{
  "scripts": {
    "prepare": "husky install"
  },
  "devDependencies": {
    "husky": "^5.2.0"
  }
}

根本原因

Husky 是一个 Git 钩子工具，通过 npm 生命周期脚本自动设置。错误通常由以下原因引起：

1. 环境变量问题：特别是在使用 nvm 管理 Node.js 版本时
2. 生产环境限制：当 NODE_ENV=production 时，devDependencies 不会被安装
3. 路径配置问题：某些终端环境无法正确访问 node_modules/.bin 目录
4. Husky 版本兼容性问题：某些版本存在已知问题

解决方案

1. 检查并设置正确的 NODE_ENV

重要

如果 NODE_ENV 设置为 production，npm 不会安装 devDependencies，导致 Husky 无法找到

# 检查当前环境变量
echo $NODE_ENV

# 设置为开发环境（临时解决方案）
export NODE_ENV=development

# 或者设置为特定环境
export NODE_ENV=local

# 然后重新安装
npm install

2. 使用 nvm 时的配置

对于使用 nvm 管理 Node.js 版本的用户，需要创建初始化脚本：

~/.config/husky/init.sh

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 可选：自动使用项目指定的 Node.js 版本
if [ -f .nvmrc ] && [ -s "$NVM_DIR/nvm.sh" ];
then
  . "$NVM_DIR/nvm.sh"
  nvm use
fi;

3. Windows 系统路径配置

对于 Windows 用户，确保 Git 的 bin 目录已添加到系统 PATH 环境变量中：

1. 添加 C:\Program Files\Git\bin 到系统 PATH
2. 重启所有终端和 IDE

4. 生产环境下的解决方案

在生产环境构建时，可以使用以下方法避免 Husky 错误：

# 方法1：忽略脚本执行
npm ci --omit=dev --ignore-scripts

# 方法2：临时移除 prepare 脚本
npm set-script prepare '' && npm install --omit=dev

5. 分步安装方法

如果上述方法无效，可以尝试分步安装：

# 1. 暂时移除 prepare 脚本
# 编辑 package.json，移除或注释掉 "prepare": "husky install"

# 2. 安装依赖
npm install

# 3. 恢复 prepare 脚本
# 取消注释或重新添加 "prepare": "husky install"

# 4. 再次安装以设置 Husky
npm install

6. 更新 Husky 版本

旧版本 Husky 可能存在兼容性问题，建议升级到最新版本：

# 更新 package.json 中的版本
"husky": "^8.0.0"

# 或者直接安装最新版
npm install husky@latest --save-dev

# 然后重新初始化
npx husky install
npm set-script prepare "husky install"

7. 重新启动开发工具

某些 IDE 和 Git 客户端（如 VSCode、GitHub Desktop）可能需要重启才能识别环境变化：

1. 完全退出应用程序
2. 重新启动
3. 再次尝试操作

验证解决方案

安装完成后，验证 Husky 是否正确安装：

# 检查 node_modules/.bin 中是否有 husky
ls -l node_modules/.bin/husky

# 检查 .husky 目录是否存在
ls -la .husky/

总结

sh: husky: command not found 错误通常与环境配置、Node.js 版本管理或安装流程有关。通过检查环境变量、正确配置 nvm、确保路径设置正确，以及可能需要的手动分步安装，可以解决大多数情况下的问题。

最佳实践

• 始终在开发环境中安装 Husky（避免在生产环境安装 devDependencies）
• 使用最新版本的 Husky 以获得最佳兼容性
• 确保所有协作开发人员环境配置一致

如果问题仍然存在，建议查看 Husky 官方文档或项目特定的配置要求。