Husky 是一个 Git hooks 工具，可以让我们在 Git 操作的特定阶段（如提交前、推送前）自动执行脚本，常用于代码质量检查、测试运行等。

安装与配置 Husky

1. 安装 Husky

1
2
3
4
5
6
7
8
9
# 使用 npm
npm install husky --save-dev

# 使用 yarn
yarn add husky --dev

# 使用 pnpm
pnpm add husky -D

2. 启用 Git hooks

1
2
3
4
5
6
7
# 初始化 Husky
npx husky init

# 或者手动创建 .husky 目录
npm pkg set scripts.prepare="husky install"
npm run prepare

3. 添加 hooks

1
2
3
4
5
6
# 添加 pre-commit hook
npx husky add .husky/pre-commit "npm test"

# 添加 commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

常用配置示例

1. Pre-commit 钩子配置

在 .husky/pre-commit 文件中：

1
2
3
4
5
6
7
8
9
10
11
12
# !/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行 lint 检查
npm run lint

# 运行测试
npm test

# 检查代码格式
npm run format:check

2. Commit-msg 钩子配置

在 .husky/commit-msg 文件中：

1
2
3
4
5
6
# !/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 使用 commitlint 检查提交信息格式
npx --no -- commitlint --edit "$1"

3. Pre-push 钩子配置

1
2
3
4
5
6
# !/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 在推送前运行完整测试
npm run test:ci

配合其他工具使用

1. 配合 ESLint

1
2
3
4
# pre-commit 文件内容
npm run lint:fix
git add .

2. 配合 Prettier

1
2
3
4
# pre-commit 文件内容
npm run format
git add .

3. 配合 lint-staged

首先安装 lint-staged：

1
2
npm install lint-staged --save-dev

然后在 package.json 中配置：

1
2
3
4
5
6
7
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,html,css,scss}": ["prettier --write"]
  }
}

在 .husky/pre-commit 中：

1
2
3
4
5
# !/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

完整配置示例

package.json 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "scripts": {
    "prepare": "husky install",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "test": "jest",
    "test:ci": "jest --ci --coverage"
  },
  "devDependencies": {
    "husky": "^8.0.0",
    "lint-staged": "^13.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "jest": "^29.0.0"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,html,css,scss,yml}": ["prettier --write"]
  }
}

.husky 目录结构

1
2
3
4
5
6
7
8
9


.husky/
├── _
│ └── husky.sh
├── pre-commit
├── commit-msg
└── pre-push

跳过 hooks（特殊情况）

在某些情况下，你可能需要跳过 hooks：

1
2
3
4
5
6
# 跳过所有 hooks
git commit -m "message" --no-verify

# 或者使用缩写
git commit -m "message" -n

最佳实践

  1. 保持 hooks 快速执行 - 避免在 pre-commit 中运行耗时很长的任务
  2. 只检查暂存区的文件 - 使用 lint-staged 只对将要提交的文件进行检查
  3. 提供清晰的错误信息 - 当检查失败时，给出明确的修复指导
  4. 团队统一配置 - 确保团队所有成员使用相同的 hooks 配置

常见问题

1. Hook 不执行

确保文件有执行权限：

1
2
chmod +x .husky/*

2. Windows 兼容性

在 Windows 系统中，确保使用 Git Bash 或 WSL 来执行 hooks。

3. 性能优化

对于大型项目，可以：

  • 使用缓存（如 ESLint cache）
  • 只检查修改的文件
  • 并行执行任务

这样配置后，Husky 会在每次提交时自动运行代码质量检查，确保团队代码风格一致且质量达标。