若需代码格式检查，再装eslint、prettier（已有可跳过） - Web前端

做前端开发时，团队里代码风格五花八门、提交前忘格式化、commit信息写得乱糟糟…这些场景是不是很头疼？Husky和lint-staged就是专门解决“git提交环节代码质量把控”的神器！但很多同学刚开始配置时一头雾水：这俩工具咋配合？配置步骤有啥坑？怎么让全团队都用上？今天用问答形式把这些问题掰碎了讲明白～

Husky和lint-staged分别是做什么的？

先聊Husky：Git本身有“钩子”机制，比如PRe-commit（提交前执行）、commit-msg（提交信息校验）这些阶段，但默认钩子文件藏在.git/hooks里，手动改既麻烦又没法同步给团队。Husky把Git钩子“前端化”——让我们能在项目里用配置文件（或脚本）定义钩子要执行的任务，还能把配置提交到仓库，团队成员装依赖后自动生效，比如想在commit前跑代码检查，用Husky就能轻松给pre-commit钩子绑任务。

再看lint-staged：它核心是“只处理Git暂存区（staged）的文件”，假设项目有几百个文件，每次全量跑ESLint、prettier特别慢，但lint-staged会智能筛选出你这次commit要提交的文件，只对这些文件做检查/格式化，效率飙升，而且它天生和Husky是“好搭档”——Husky负责“什么时候跑任务”，lint-staged负责“精准跑哪些文件的任务”。

为什么非要在Git钩子环节加代码检查？

得从团队协作的痛点说起：

• 代码规范难统一：新人不懂团队规则，提交未格式化代码、用了禁用语法，revIEwer反复提意见太浪费时间，用Git钩子在提交前强制检查，能从源头把住风格关。

• 问题暴露太晚：如果等到CI/CD流水线才检测代码问题，修复成本高（比如构建失败后再回退代码），Git钩子是“本地提交前”的最后一道闸，提前拦截错误更高效。

• 提交信息没规范：有人写“改了点东西”，后续查commit记录根本不知道改了啥，用commit-msg钩子配合commitlint，能强制提交信息格式（如feat: 新增用户权限模块），让历史记录清晰可读。

举个真实场景：之前团队里有个同学改了登录页样式，没运行prettier，提交后代码格式乱成一团，后来用Husky+lint-staged，pre-commit钩子自动跑prettier格式化暂存区文件，再也没出现这种情况。

从零开始，怎么配置Husky + lint-staged？

假设是react/vue这类前端项目（已装node.js），分步骤实操：

初始化项目（已有项目可跳过）

新仓库先执行npm init -y生成package.json。

安装核心依赖

npm install husky lint-staged --save-devnpm install eslint prettier eslint-config-prettier eslint-plugin-prettier --save-dev

配置lint-staged（筛选文件+执行任务）

在package.JSON里加lint-staged字段，比如对JS/JSX文件做eslint检查+prettier格式化：

{
  "lint-staged": {
    "*.{js,jsx}": [
      "eslint --fix",  // 自动修复eslint问题
      "prettier --write"  // 自动格式化
    ],
    "*.{CSS,Less,scss}": [
      "stylelint --fix"  // 假设用stylelint做css检查
    ]
  }
}

规则是“匹配暂存区的js/jsx文件，先跑eslint自动修复，再用prettier格式化”。

初始化Husky并绑定Git钩子

执行npx husky install，项目根目录会生成.husky文件夹（存Git钩子脚本）。

给pre-commit钩子绑任务：

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

执行后，.husky/pre-commit文件里会有npx lint-staged——意思是“commit前先执行lint-staged的检查/格式化”。

扩展：用commitlint规范提交信息（可选但推荐）

想管commit信息格式？装commitlint：

npm install @commitlint/cli @commitlint/config-conventional --save-dev

创建commitlint配置文件（如.commitlintrc.js）：

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

给commit-msg钩子绑任务：

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

这样提交信息不符合feat: xxx、fix: xxx等规范时，commit会被拦截。

配置时最容易踩的5个坑，怎么避？

Husky版本兼容问题（v4 vs v7+）

Husky旧版本（v4）用husky.config.js配置，新版本（v7+）改用.husky文件夹管理脚本，若团队有人用老版本，npx husky install可能没反应。解决方案：package.json指定husky版本，或用prepare脚本自动初始化：

{
  "scripts": {
    "prepare": "husky install"
  }
}

prepare在npm install后自动执行，新人装依赖时husky会自动初始化。

lint-staged匹配规则写错

想匹配src目录下所有js文件，写成src/*.js只会匹配src下一级，子文件夹不生效，要写成src/**/*.js（表示递归子目录），多文件类型用逗号分隔时，大括号外要加引号（如"*.{js,jsx}"），避免终端解析错误。

钩子脚本没执行权限

windows系统下生成的.husky/pre-commit可能没执行权限，导致钩子不触发。解决方案：linux/Mac执行chmod +x .husky/pre-commit手动加权限；或确保husky安装时自动处理权限。

ESLint和Prettier配置冲突

同时用eslint和prettier，易出现“eslint修复后prettier又改回去”，要装eslint-config-prettier（关闭eslint与prettier冲突的规则）和eslint-plugin-prettier（把prettier错误当eslint错误报），并在.eslintrc.js配置：

module.exports = {
  extends: ['plugin:prettier/recommended']
};

钩子执行时报“命令找不到”

装了eslint但全局没装，钩子脚本里用eslint会报错。解决方案：用npx执行（如npx eslint），或把命令写进package.json的scripts里（如"lint": "eslint src"），再通过npm run lint调用。

实际项目里，怎么定制更灵活的检查逻辑？

多工具组合：Stylelint + Commitlint + 单元测试

• CSS检查：用stylelint处理暂存区的css/less文件，在lint-staged里加"stylelint --fix"。

• 提交信息：commitlint强制格式，甚至团队自定义提交类型（如chore: 升级依赖、docs: 更新README）。

• 预推送检查：在pre-push钩子跑单元测试（npx husky add .husky/pre-push "npm run test"），避免推送有bug的代码。

结合业务的特殊检查

比如团队要求“所有页面组件必须有proptypes定义（React项目）”，可写自定义脚本，在lint-staged里执行：

{
  "lint-staged": {
    "src/components/**/*.jsx": [
      "node scripts/checkPropTypes.js"  // 自定义脚本检查propTypes
    ]
  }
}

每次提交组件文件时，会自动跑这个业务检查。

怎么让团队所有人都能用上这套钩子？

把配置塞进仓库，自动初始化

• 把.husky文件夹、lint-staged配置（package.json里的字段）、eslint/prettier/commitlint的配置文件全提交到Git仓库。

• 用package.json的prepare脚本自动执行husky install，新人npm install后，husky会自动初始化，钩子生效。

写清晰的文档+示例

在README.md里说明：“提交代码前会自动跑lint-staged，若有格式错误会自动修复；如果修复后有未暂存的变更，需要重新add再commit”，再贴个常见错误的解决例子（比如commit信息不规范时的提示），降低团队学习成本。

Husky + lint-staged的底层原理是啥？

简单拆解：

• Git钩子机制：Git在commit、push等操作前/后，会去.git/hooks找对应脚本执行，Husky的作用是“接管”这些钩子文件，把我们配置的脚本注入进去，让前端能通过npm包管理钩子逻辑。

• lint-staged的筛选逻辑：它会先获取当前Git暂存区的文件列表，再根据我们配置的文件匹配规则（如*.js）筛选目标文件，最后对这些文件执行指定命令（如eslint），因为只处理改动的文件，所以比全量检查快很多。

这套工具链本质是“用技术手段把代码规范‘自动化’”——从提交前的格式检查，到提交信息的规范，再到推送前的测试拦截，全方位保障代码质量，配置时踩坑很正常，但只要理解每个工具的作用和协作逻辑，再结合团队需求定制，就能让Git钩子成为团队协作的“隐形质检员”～

标签：已有跳过再装若需代码格式