在 Mac 上的 Codex 项目里，想要实现每次 Git 提交前自动执行 ESLint 代码检查，Husky 是不可或缺的核心工具。然而实际配置过程中容易遇到各种坑——需要正确初始化 Husky、配置 lint-staged、设置 pre-commit 钩子，还要处理 Mac 环境下特有的权限问题、Shell 兼容性以及 nvm 版本管理冲突。下面将整个流程拆解开来，每一步都附上容易忽略的细节，确保配置顺利。

简单概括就是：每次执行 git commit 时自动触发代码规范检查，防止不符合规范的代码流入仓库。要实现这一目标，关键在于让 Husky 正确加载并成功触发 lint-staged 流程。

初始化 Husky 并启用钩子目录

首先打开终端，进入项目根目录，安装 Husky：

npm install husky --save-dev

然后运行初始化命令：

npx husky init

这一步会在项目根目录生成 .husky 文件夹，并自动在 package.json 中添加 prepare 脚本。如果未自动生成，可手动补充：

npm set-script prepare "husky install"

务必执行 npm run prepare——只有这一步才能真正激活钩子。否则 .husky/pre-commit 等脚本 Git 不会识别，相当于配置无效。

配置 pre-commit 钩子以执行 lint-staged

确保已安装 lint-staged：

npm install lint-staged --save-dev

然后在 package.json 中添加 lint-staged 配置（非强制，但强烈推荐）：

"lint-staged": { "src/**/*.{js,jsx,ts,tsx}": ["eslint --fix", "git add"] }

接着创建 pre-commit 钩子：

npx husky add .husky/pre-commit "npx lint-staged"

此时 .husky/pre-commit 文件内容应为一段可执行的 shell 脚本：第一行是 #!/bin/sh，第二行是 . "$(dirname "$0")/_/husky.sh"。如果缺少第二行，需手动补上——否则在 Mac 系统下钩子很可能静默失效，连错误提示都没有。

验证 Husky 是否生效

配置完成后需要进行验证，这里提供三种方法：

方法一：手动触发测试
修改一个 JS 文件，故意违反 ESLint 规则（例如删除一个分号），然后执行：
git add . && git commit -m "test lint"

方法二：检查钩子是否注册成功
直接查看文件内容：
cat .husky/pre-commit
如果输出中包含 npx lint-staged，说明钩子已正确写入。

方法三：查看 Git 当前激活的钩子路径
执行：
git config --list | grep hook
如果输出显示 core.hooksPath=.husky，说明 Husky 已成功接管 Git 的钩子系统。

解决 Mac 常见权限问题

在 Mac 上运行 Husky，最常遇到的故障是权限和 Shell 兼容性问题。按以下三步处理：

第一步：为钩子文件添加执行权限
chmod +x .husky/pre-commit

第二步：确认 Shell 环境兼容
Mac 默认使用 zsh，而部分旧版 Husky 生成的脚本以 #!/bin/sh 开头。如果遇到 /bin/sh: npx: command not found 错误，请将 .husky/pre-commit 第一行改为 #!/bin/zsh。

第三步：绕过 Node 版本冲突（仅在使用 nvm 时适用）
如果你用 nvm 管理 Node 版本，钩子脚本可能找不到 node 或 npx。解决办法是在 .husky/pre-commit 顶部插入以下两行，加载 nvm 环境：

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

这样 Husky 就能在正确的 Node 版本下执行 lint-staged 了。