husky + lint-staged 常用命令

husky 用于管理 Git Hooks，lint-staged 用于对暂存区的文件执行检查。两者配合可以在 git commit 时自动检查代码质量。

为什么需要

• husky：在 Git 操作（commit、push 等）时自动执行脚本
• lint-staged：只检查本次修改的文件，而不是整个项目，速度更快

典型工作流：

git add . → git commit → husky 触发 pre-commit → lint-staged 检查暂存文件 → 通过则提交

安装

# 安装依赖
npm install -D husky lint-staged

# 初始化 husky（创建 .husky 目录）
npx husky init

配置

配置 pre-commit 钩子

# 编辑 .husky/pre-commit 文件
npx lint-staged

配置 lint-staged

在 package.json 中添加：

{
  "lint-staged": {
    "*.{js,ts,vue}": "eslint --fix",
    "*.{js,ts,vue,css,scss,json,md}": "prettier --write"
  }
}

或创建独立配置文件 .lintstagedrc.json：

{
  "*.{js,ts,vue}": "eslint --fix",
  "*.{js,ts,vue,css,scss,json,md}": "prettier --write"
}

完整示例

{
  "scripts": {
    "lint": "eslint src/",
    "format": "prettier --write src/",
    "type-check": "vue-tsc --noEmit"
  },
  "lint-staged": {
    "*.{js,ts,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write"
    ]
  }
}

常用命令

husky 命令

# 初始化 husky（创建 .husky 目录）
npx husky init

# 添加钩子（husky v8 命令，v9+ 已废弃）
npx husky add .husky/pre-commit "npx lint-staged"
npx husky add .husky/pre-push "npm run type-check"

# 手动执行钩子（调试用）
npx husky .husky/pre-commit

⚠️ husky v9+ 不再支持 npx husky add，直接创建钩子文件即可：

# husky v9+ 添加钩子
echo "npx lint-staged" > .husky/pre-commit
echo "npm run type-check" > .husky/pre-push

husky v8 vs v9 主要区别

特性	husky v8	husky v9
添加钩子	npx husky add	直接创建文件
初始化	npx husky install	npx husky init
钩子目录	.husky/	.husky/
配置方式	package.json prepare 脚本	package.json prepare 脚本
Node 版本	Node.js 14+	Node.js 18+

💡 v9 的 init 命令替代了 v8 的 install，并且自动在 package.json 中添加 prepare 脚本。

lint-staged 命令

# 手动执行（调试用）
npx lint-staged

# 指定配置文件
npx lint-staged --config .lintstagedrc.json

常见 Git Hooks

钩子	触发时机	常见用途
pre-commit	git commit 之前	代码检查、格式化
commit-msg	提交信息写入后	检查提交信息格式
pre-push	git push 之前	类型检查、运行测试
pre-rebase	git rebase 之前	阻止对特定分支 rebase

配合 commitlint

commitlint 用于规范化 Git 提交信息格式。

安装

npm install -D @commitlint/cli @commitlint/config-conventional

配置

创建 commitlint.config.js：

module.exports = {
  extends: ['@commitlint/config-conventional'],
}

添加 commit-msg 钩子

npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"

提交信息格式

<type>(<scope>): <subject>

# 示例
feat: 添加用户登录功能
fix(auth): 修复 token 过期问题
docs: 更新 README
style: 格式化代码
refactor: 重构登录逻辑
test: 添加登录测试
chore: 更新依赖

type	说明
feat	新功能
fix	修复 bug
docs	文档更新
style	代码格式（不影响逻辑）
refactor	重构
test	测试相关
chore	构建/工具变动

Vue / Vite 项目完整配置示例

安装依赖

npm install -D husky lint-staged eslint prettier @commitlint/cli @commitlint/config-conventional

初始化 husky

npx husky init

配置 pre-commit 钩子

# .husky/pre-commit
npx lint-staged

配置 commit-msg 钩子

# .husky/commit-msg
npx --no -- commitlint --edit $1

package.json 配置

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "lint": "eslint src/",
    "lint:fix": "eslint --fix src/",
    "format": "prettier --write src/",
    "type-check": "vue-tsc --noEmit",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,ts,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write"
    ]
  }
}

commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
}

提交信息格式

<type>(<scope>): <subject>

# 示例
feat(auth): 添加用户登录功能
fix(api): 修复 token 过期问题
docs: 更新 README

---

常见问题

提交时 husky 不执行

# 确认 .husky 目录存在
ls .husky/

# 确认钩子文件有执行权限（macOS/Linux）
chmod +x .husky/pre-commit

# 重新初始化
npx husky init

跳过钩子（紧急情况）

# 跳过 pre-commit 钩子
git commit --no-verify -m "emergency fix"
git commit -n -m "emergency fix"

⚠️ 仅在紧急情况下使用 --no-verify，正常开发应确保钩子通过。

Windows 下钩子不生效

# 确保 Git 使用 bash 执行钩子
git config core.hooksPath .husky

参考

• husky 官方文档
• lint-staged GitHub
• commitlint 官方文档