Husky项目：解决Monorepo中Git钩子失效问题的最佳实践

在Monorepo架构下使用Husky管理Git钩子时，开发者常会遇到钩子脚本不执行的问题。本文通过一个典型场景分析，深入讲解问题根源和解决方案。

问题现象分析

当项目采用Monorepo结构时，.git目录通常位于仓库根目录，而前端项目（如Next.js应用）可能位于子目录（如./client）。此时若将Husky安装在子项目的package.json中，按照常规配置方式创建的pre-commit钩子可能会失效。

典型症状包括：

• 提交时代码检查未自动执行
• 即使脚本中包含exit 1强制失败命令，提交仍能成功
• 钩子文件权限正常但未被Git识别

根本原因

1. 目录结构错位：Husky 9.x版本改变了文件结构要求，需要将钩子文件直接放在.husky目录下，而非子目录中
2. 路径解析问题：在Monorepo中，相对路径引用可能导致脚本执行时上下文错乱
3. 初始化顺序：prepare脚本的执行位置会影响Husky的安装路径

解决方案

正确的文件结构

项目根目录/
├── .git/
└── client/
    ├── .husky/
    │   ├── pre-commit      # 直接放在这里，不在_子目录下
    │   └── h               # 自动生成的辅助文件
    └── package.json

关键配置要点

1. prepare脚本调整：

{
  "scripts": {
    "prepare": "cd .. && husky client/.husky"
  }
}

2. pre-commit文件内容：

#!/usr/bin/env sh
. "$(dirname "$0")/h"

# 明确指定工作目录
cd ./client && npx lint-staged

3. 权限设置： 确保钩子文件具有可执行权限：

chmod +x .husky/pre-commit

进阶建议

1. Monorepo统一管理：考虑在根目录安装Husky，通过--filter参数管理子项目
2. 环境变量检查：在脚本开头添加pwd命令输出，确保执行路径符合预期
3. 版本兼容性：Husky 7.x与9.x的配置方式有显著差异，需注意版本对应

验证方法

1. 手动测试钩子：

./.husky/pre-commit

2. 检查Git配置：

git config core.hooksPath

3. 查看调试信息：

HUSKY_DEBUG=1 git commit -m "test"

通过以上配置和验证步骤，可以确保Husky在Monorepo环境中可靠工作，实现提交前的自动化代码检查流程。