在不少前端团队待过，我发现真正决定代码质量与提交效率的分水岭，往往不在代码评审，而在 git commit 之前那一下。Husky 负责把 Git Hooks 变成团队共享的工程规范，lint-staged 则把 lint 和格式化限定在暂存区文件上，保证每次提交只检查自己这次改动的东西。这篇文章我会把这两个工具的底层机制、版本差异、配置玩法、以及实际项目中会遇到的坑一次讲透，让团队能真正把提交规范落到日常操作里。
1. 这俩工具解决的根本问题：为什么不该全仓跑 lint
很多人第一次接触 husky + lint-staged 时有个疑问：我直接在 package.json 里写个 lint 脚本，提交前跑一遍不行吗？行，但代价很快会让你受不了。我见过不少项目在 pre-commit 里写npm run lint，结果提交一次要等半分钟甚至几分钟，后来大家纷纷绕过 hook。这个问题不是 hook 机制造成的，而是"范围"选错了。
1.1 全仓 lint 的性能陷阱与误报
全仓 lint 的问题主要体现在三方面。第一是性能：一个中大型前端项目可能有几千个组件文件，每次提交都全量扫描，跑脚本的耗时是分钟级的。就算用 ESLint 的缓存，首次运行时冷启动加上大文件解析，依旧非常难受。第二是历史质量问题：老项目里大量历史遗留代码本来就没过 lint 规则，可能欠了一堆any、未使用变量、console.log。如果每次提交都全量跑，哪怕你只改了一行注释，也会被这些历史债拦住。第三是误报干扰：当你紧急修 Bug 提交时，lint 出来几十个和本次改动毫无关系的旧错误，你会被迫去改那些不相干的代码，改出问题谁来负责？
lint-staged 的思路简单粗暴却非常有效：只拿这次进入暂存区（staged）的文件去跑规则。它通过git diff --staged --name-only之类的指令拿到文件列表，再做 glob 匹配，只对匹配上的文件执行 lint 和 format。这样本地 100ms 能完成的事绝不让全仓库承担，你提交的每一行代码都是经过校验的，历史问题不会被反复翻出来。
1.2 Git Hooks 的原始样子与痛点
Git 自带的 Hooks 机制本身就是给这个场景准备的。每个 Git 仓库下都有一个.git/hooks/目录，里面有pre-commit、commit-msg、pre-push等模板。你要是进去看一眼会发现，它们默认是不能直接执行的示例脚本。
问题是：这些文件藏在.git目录里，.git这个目录天然不被版本库跟踪。也就是说，你在自己机器上改好 pre-commit 逻辑，同事 clone 仓库之后根本不会拿到这个 hooks。以前我见过不少团队用的是"管理员手动拷贝"或"写个 shell 脚本来安装 hooks"这种土办法，一旦有人 clone 后忘了跑安装脚本，整个规范对他来说就是透明的，想怎么提就怎么提。
Husky 解决的正是"让 hooks 配置跟着仓库走，并且能自动生效"。它把你写的 pre-commit 脚本放到项目根目录的.husky下，然后通过 git 的core.hooksPath配置让 Git 把 hooks 指向这个目录。因为.husky是普通目录，会被 git 跟踪，所以团队成员只要正常安装依赖，hooks 就已经配好。这个设计比 v4 时代在 node_modules 里动态写.git/hooks要清晰得多，后面会详说版本差异。
2. Husky 的版本演进与配置迁移：从 v4 到 v7 的坑
Husky 这几年迭代了不少破坏性版本，很多老项目升级时卡住，就是因为没理解它"换了一个实现方式"。我自己是从 v4 时代用起的，经历过迁移到 v6、v7 的过程，这里面有几个必须搞清楚的变化点。
2.1 v4 的 .huskyrc 与 Node 机制
Husky v4（以及更早的 v1~v3）的配置方式是写在package.json里：
{ "husky": { "hooks": { "pre-commit": "npm run lint", "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } } }它利用 npm 安装依赖时的postinstall钩子，在node_modules/husky内部执行一段脚本，把上述命令改写到 .git/hooks 下面生成实际的 hook 脚本。所以只要你在项目里npm install过 husky，hooks 就被动态写到了本地的.git/hooks里。
v4 用起来确实方便，但有明显问题。一是它依赖 npm 的执行时机，如果团队用的是 pnpm 或者 yarn v2（PnP 模式），或者你直接git clone之后还没装依赖，hook 就不存在。二是它是往.git/hooks里写文件，这个目录不受 git 管理，所以不同成员之间很容易因为 node_modules 安装环境不同导致 hooks 版本不一致。三是老版本里嵌套仓库、子模块的场景经常失效。
2.2 v6/v7 的 prepare 脚本初始化与核心钩子
Husky v5 开始彻底改变了方案：不再往.git/hooks里写脚本，而是让 git 通过core.hooksPath指向项目根目录下的.husky文件夹。你项目里的 hooks 文件本身是普通文本文件，因此能被 git 用普通 diff 跟踪，团队成员看到的就是一个文件。
到了 v6、v7，官方推荐的初始化方式是：
npx husky init或者拆分理解：
npm pkg set scripts.prepare="husky install" npm run prepare其中npm pkg set会在 package.json 中写入：
{ "scripts": { "prepare": "husky install" } }prepare脚本非常关键：无论是npm install、npm ci，还是git clone后第一次npm install，npm 都会自动执行prepare脚本。也就是说husky install会在装依赖阶段自动被执行，然后把.husky目录找出来并设置core.hooksPath指向它。
如果你用的是 pnpm，同样建议保留prepare，不过 pnpm 版本较新时要注意 pnpm 默认也会执行prepare，但如果是构建服务器场景时需要--ignore-scripts的情况，就得手动跑一次husky install。
整个流程下来，最直接的判断方法就是：
git config core.hooksPath正常配置下，输出应该是.husky（相对路径）。如果这条命令什么都不输出，说明 hooks 没被启用。
2.3 常见坑：dubious ownership、.git 目录与权限
迁移到新版本后，最容易踩的坑有三个。
第一个是dubious ownership。很多团队项目放在/home/xxx/shared_folder或者/workspace/这种挂载目录、从 Windows 访问 WSL 的/mnt目录、或者公司统一挂载的盘符里，git 会提示类似：
fatal: detected dubious ownership in repository at '/path/to/repo'这是 Git 为了防攻击引入的安全机制，因为仓库目录所有者与当前用户不一致。第一次遇到别慌，用安全的全局方法：
git config --global --add safe.directory /path/to/repo但要提醒团队注意：不要为了省事直接safe.directory *。如果整个系统配了全部目录可信，安全防护等于没开。规范做法是把具体路径加进去。在项目根目录跑mkdir -p .husky后如果发现husky install报这个错，先确认是不是这个原因，再逐一加白名单。
第二个坑是hooks 文件没有执行权限。husky init生成的.husky/pre-commit文件默认是带x权限的，但如果你用husky add手动添加 hook，或者在 Windows 上通过某种编辑器保存，文件权限可能会丢。Git 在运行 hook 时会先检查这个文件是否可执行，不可执行会直接跳过（这也是"明明配了 hook 却不生效"的一个经典原因）。排查方法：
ls -l .husky/pre-commit如果没有-rwxr-xr-x里的 x，执行：
chmod +x .husky/pre-commit第三坑是把 hooks 误配到了别的目录。比如项目用了 monorepo，子包内部也放了.husky，但core.hooksPath是仓库级别的，它只能有一个指向。如果仓库根目录和子目录都初始化了 husky，最后谁后执行谁覆盖，很容易出现"改了子包 hook 不生效，改根目录的才对"。所以 monorepo 建议统一在根目录维护一套.husky文件，子包不要各自初始化。
3. lint-staged 的工作机制与实际匹配玩法
理解 lint-staged，核心是认清它其实是一个"中转调度器"。它自己不负责具体规则，只是把暂存区文件名读出来、按 glob 过滤，然后分发给 eslint、prettier 等工具去执行。它最值钱的设计在于“自动把修改后的文件再加回暂存区”，这个细节如果不理解，会踩很多自以为是的坑。
3.1 暂存区数据流：为什么它只处理暂存文件
Git 的提交流程里，开发者的改动先在工作区，然后git add把内容放进暂存区（Index）。最终git commit打包的是暂存区的内容，而不是工作区的全部。如果 hook 里去 lint 工作区的文件，那么你和同事看到的可能是"改了一半代码"的中间状态，lint 结果就会忽好忽坏。
lint-staged 的做法是：站在"暂存区"这一侧，只列出已经被git add过的文件，对这些文件运行命令。这样做有另一个隐藏好处——如果你的 lint 规则带了自动修复（--fix），修改发生在工作区的文件上，此时文件内容和暂存区内容又不一致了。如果让它孤零零地在暂存区里躺着，commit 提交的还是修复前的代码，那你这个修复等于白做了。所以 lint-staged 在命令执行完以后，会检查哪些文件被改动了，然后自动git add它们，保证修复结果真的进入本次提交。
这个"重新暂存"的动作从 v10 之后基本是默认行为，你不需要在命令列表里额外写git add。但要注意：如果格式化工具做了删除或重命名文件的操作，自动 add 可能无法覆盖所有变化，极端情况下还是要人工确认。
3.2 glob 匹配规则细节与多文件类型配置
lint-staged 的匹配引擎底层是 minimatch（类 glob）。它接收的是相对于仓库根目录的路径，默认会忽略.gitignore中排除的文件（因为那些文件根本不会进暂存区）。常用写法：
{ "*.{js,ts,jsx,tsx}": "eslint --fix", "*.{css,scss,less}": "stylelint --fix", "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write" }注意：这里*.{js,ts}只会匹配当前目录和子目录下所有对应扩展名文件吗？准确说，*.js在 minimatch 里默认不递归，会匹配所有层级（因为 minimatch 与 shell glob 的隐式递归不同），lint-staged 官方文档告诉我们，如果写在配置里的 key 没有斜杠，它会自动用**/前缀预处理。也就是说"*.js"相当于"**/*.js"，会匹配所有目录层级里的 JS 文件。如果你只想匹配 src 下的文件，可以写：
{ "src/**/*.{js,ts}": "eslint --fix" }这里要注意**/的语义和普通 shell 不一样：src/**/*.ts会匹配src/a.ts和src/a/b.ts，属于常见认知。更稳妥的做法是始终在配置里写明确路径。
另一个细节：同一个文件被多条规则命中时，命令执行顺序是数组内串行、global 数组间并行的。比如：
{ "*.js": ["eslint --fix", "prettier --write"] }这个配置会对同一个.js文件先跑 eslint，再跑 prettier，串行执行。但要是在同一层级再写一个"*.js": ["cmd"]，JSON 里 key 重复了，这本身就不是有效的对象语义，所以不要这样写。lint-staged 用对象配置时，最高效的做法是让不同文件类型的规则并行跑，而对同一文件的多个工具用数组串行，避免格式化与 lint 之间互相覆盖。
3.3 任务执行器：数组命令、函数与动态重暂存
lint-staged 的命令值除了写字符串，还可以写成数组或函数，这是它的进阶玩法。
数组形式就是按序执行：
{ "*.ts": ["prettier --write", "eslint --fix", "tsc --noEmit"] }函数形式给了你更大灵活性。例如你想把多个文件名拼到一条命令里减少 ESLint 进程数：
{ "*.{ts,tsx}": (filenames) => [ "prettier --write " + filenames.join(" "), "eslint --fix " + filenames.join(" ") ] }不过要小心：文件名里如果带空格，直接 join 会把路径拆散导致命令失败。更稳妥的做法是用相对路径（lint-staged 传进来的默认就是相对路径）再配合 shell 的引用处理。lint-staged 也提供了filenames的完全形式（filenames) => ...。在大型 monorepo 里，你可以让函数根据文件所在目录动态拼接--config参数，比如给packages/a的文件用专属 eslint 配置。
函数返回 false 或空数组时，表示"本次没有命令要执行"。这个特性很适合做有条件的检查，比如只对新增文件做某些严格校验，而修改文件只做基础检查。
最后提一下 lint-staged 的 stash 机制。默认情况下，它会用git stash把未暂存的工作区改动临时保存，待命令执行完再恢复。这样做是为了确保被检查的暂存区内容不受到未暂存改动的影响。有几个参数可以调节：--no-stash关闭 stash（可能影响检查到未暂存的内容），--diff=...指定 diff 基准。在正常开发流程里，使用默认 stash 就好，但如果你在命令里用了体积很大的依赖，stash 偶尔会闪出Saved working directory and index state这种日志，不必害怕。
4. 组装一套完整的 husky + lint-staged 提交流水线
理论讲了不少，下面直接给一套能抄作业的初始化流程。以一个前端项目为例，同时加入 ESLint、Prettier、Stylelint 和 commitlint，让 pre-commit 管代码规范，commit-msg 管提交信息格式。
4.1 环境准备与脚手架初始化
首先确保项目是 git 仓库：
git init然后安装依赖。以 npm 为例：
npm install -D husky lint-staged eslint prettier stylelint commitlint @commitlint/cli @commitlint/config-conventional初始化 husky。新版直接：
npx husky init这句话会做几件事：创建.husky/目录、写入.husky/pre-commit示例、在 package.json 里添加prepare脚本（如果还没有的话）。如果你希望更精确，也可以手工走一遍：
npm pkg set scripts.prepare="husky install" npm run prepare npx husky add .husky/pre-commit "npx lint-staged"husky add其实就是创建 hook 文件并写入一行命令。注意它要求第一行有 shebang，husky 会自动补#!/usr/bin/env sh。我见过很多人手动创建.husky/pre-commit时漏了这行，导致 hook 无法被正确执行。
4.2 eslint + prettier + stylelint + commitlint 的组合配置
把.husky/pre-commit设置为：
npx lint-staged然后在package.json里配置：
{ "lint-staged": { "*.{js,jsx,ts,tsx,vue}": [ "eslint --fix", "prettier --write" ], "*.{css,scss,less,vue}": [ "stylelint --fix", "prettier --write" ], "*.{json,md,html,yml,yaml}": [ "prettier --write" ] } }这里有个常见的顺序选择：先 eslint 还是先 prettier？通常先跑 eslint --fix 再跑 prettier --write。因为 prettier 负责格式统一，它在修复后不会破坏 eslint 规则；而 eslint 的 fix 可能会改变一些格式，放到前面更接近"人工拼好后交给 formatter 统一"的逻辑。如果你项目里同时用eslint-config-prettier关闭冲突规则，那么两者怎么跑都不会有语法冲突。
再添加 commitlint hook：
npx husky add .husky/commit-msg "npx --no-install commitlint --edit \$1"注意$1需要转义，因为它是 commit 临时消息文件的路径。commitlint 的校验规则配置在commitlint.config.js：
module.exports = { extends: ['@commitlint/config-conventional'] };这样pre-commit负责代码质量，commit-msg负责提交信息格式，两个 hook 职责清晰，互不干扰。
4.3 package.json 里的 scripts 设计
工程化项目建议把检查命令封装成 scripts，lint-staged 里的命令可以直接复用 scripts，也能直接写二进制。我习惯在 package.json 里定义：
{ "scripts": { "lint": "eslint . --ext .js,.ts,.vue", "format": "prettier --write .", "lint:fix": "eslint . --fix --ext .js,.ts,.vue", "typecheck": "tsc --noEmit", "prepare": "husky install" } }但注意：lint-staged 里不要直接写npm run lint。为什么？因为 lint-staged 需要把文件列表传给具体工具才能只处理暂存文件，而你npm run lint里的eslint .是扫描全仓库，这样就违背了 lint-staged 的初衷。lint-staged 的工作方式是把匹配到的文件路径作为参数追加到命令后面，所以命令应该是eslint --fix而不是eslint .。
在 TypeScript 项目里，很多人纠结要不要在 pre-commit 里做类型检查。lint-staged 文档里的一个经典方案是：
{ "src/**/*.{ts,tsx}": () => "tsc --noEmit -p tsconfig.json" }注意这里函数返回的是单条命令，没有把文件列表拼进去，相当于在 pre-commit 里跑一次全量类型检查。这在中小项目没问题，但大项目会慢。想只对暂存文件做类型检查很别扭，因为类型检查本质上是项目级的操作。所以我的经验是：如果团队 CI 会跑 typecheck，本地 pre-commit 就不要再阻塞；如果希望本地尽快暴露类型错误，就接受一点全量 typecheck 的耗时，把它塞进 pre-commit。二选一，别两边都堵。
5. 真实踩坑记录：错误处理、忽略文件与跨平台问题
再完美的配置也架不住真实环境的复杂性。下面这些坑几乎每个项目都会遇到，我把排查链路写出来，大家可以照方抓药。
5.1 文件没有被 lint 的原因排查
有同学反馈："我明明配了 pre-commit 也看到 lint-staged 在跑，但某几个文件没被 lint。"逐层排查很重要。
首先确认文件确实进了暂存区。lint-staged 只处理git add过的文件，如果文件只是改了没 add，它不可能去检查。这是因为它的设计原则是"只检查即将提交的东西"。于是要git add改过的文件，再尝试 commit。
其次看 glob 是否匹配。比如你改了config/settings.ts，配置写的是"*.js": [...]，那当然不会匹配。用npx lint-staged --verbose可以看到实际匹配到的文件列表，非常直观。
接着检查忽略配置。ESLint 默认会读取.eslintignore，Prettier 默认读取.prettierignore。假如你的 prettier 配置里忽略了dist/**，lint-staged 匹配到dist/xx.js后执行 prettier，prettier 会直接跳过不做输出，看起来就是没有处理。如果你想强制 lint，在配置中递交给工具的路径是绝对的，工具仍会受自身 ignore 配置影响，所以要么调整 ignore 规则，要么在命令参数里加--no-ignore（但通常不建议这样做）。
最后确认命令本身是否执行成功。如果 eslint 命令先失败，后面的 prettier 可能不会执行（默认任一命令失败会中断并阻止提交）。你可以让 lint-staged 在 debug 模式下运行：
npx lint-staged --debug它会把每次读取的暂存文件列表、匹配结果、命令执行状态全部打印出来。
5.2 Windows 下命令执行异常
Windows 玩家最常见的两个报错，一个是npx: command not found，另一个是"." is not recognized as an internal or external command。
原因在于 husky 的 hook 文件是用 shell 脚本写的，Windows 上执行时默认走 Git Bash 的 shell。Git Bash 能识别npx，但如果你没有把 Node 的全局 bin 目录放进 PATH，或者你是通过 NVM、fnm之类装的 Node，Git Bash 可能找不到 npx。常见的解决办法是：在.husky/pre-commit开头手动导出 PATH。比如：
#!/usr/bin/env sh export PATH="$HOME/.nvm/versions/node/v20.11.0/bin:$PATH"但这没法让整个团队统一。更好一点的方式是把 Node 目录写成一个公用的脚本，放到.husky/_目录里，然后 hook 里source .husky/_/path.sh。还有一种思路是不要去 shell 里找 npx，而是直接调用本地二进制：
#!/usr/bin/env sh . "$(dirname "$0")/_/husky.sh" node_modules/.bin/lint-staged但这样绕过了 npx 的版本查找逻辑，也有她自己的坑。我更推荐的做法是保持命令简单，且让 husky 自己生成的 sh 头正常工作。如果在 Windows 上遇到路径问题，可以把 hook 里的命令改成npm exec lint-staged，npm 会自行解析 PATH，往往比npx更稳。
另一个细腻的坑是行尾符。如果项目 git 配置了core.autocrlf=true，hook 文件在 checkout 时可能被转成 CRLF 导致 shell 无法执行。建议在项目根目录加.gitattributes：
.husky/** linguist-language=Shell .husky/* text eol=lf确保 husky 目录在 Windows 上保持 LF。如果不放心，可以git config core.autocrlf false后将 hooks 重写一遍再提交。
5.3 与 CI 的配合：commit 前拦截与管道复用
很多团队本地配了 husky + lint-staged，但在 CI 上又跑一套不同的 lint 命令，导致本地能过、CI 挂。其实正确思路应该是：本地 hook 做"快速拦截"，CI 做"完整把关"。
比如本地 lint-staged 只检查暂存文件，CI 可以做全量 lint 和 typecheck。这个分工是合理的，但两者之间的规则集（eslint config、prettier config、commitlint config）必须同一套。你可以把配置抽成同一份配置文件，CI 只执行npm run lint，本地 hook 复用同一个 eslint 命令，只是传入文件列表不同。这样就不会出现"本地用相对宽松的配置，CI 用严格配置"这种双标。
另外要注意，lint-staged在 CI 上一般不需要跑。CI 是从 git 拉下来的完整仓库，没有"暂存区"概念。如果非要在 CI 模拟 pre-commit，可以用--diff=HEAD~1来检查最近一次提交的文件列表，但这通常是不必要的复杂化。我的建议是 CI 专注于全量校验，本地 hook 专注高频反馈。
还有个小经验：pre-push 这个 hook 也值得加。pre-commit 只校验暂存区，但某些同学会绕过它（比如git commit --no-verify）。如果你希望防得牢一点，可以在.husky/pre-push里写：
npx lint-staged --diff HEAD~1或者直接跑全量 lint。不过要看团队是否接受 push 前的等待时间。我个人更倾向于信任 pre-commit 加上 code review，pre-push 留给 CI 去把守，不要层层设卡把人惹毛。
6. 写到最后：一些个人用的顺手技巧
这几年的工程化落地经验里，我最想强调的一点是：工具链的配置一定要保持"最小惊讶原则"。不要在一个 hook 里堆太多命令，不要把 lint-staged 的 glob 写得太花哨。真正能让团队长期执行的，永远是那条一秒钟就跑完、改坏了会立刻报错的简单命令。
我自己的习惯是，在.husky/pre-commit里只放一句npx lint-staged，把所有的文件类型和命令交给 lint-staged 统一管理。当团队里有人想加新规则时，只需要改 package.json 或者lint-staged.config.js，不用去动 shell 脚本。另一个技巧是把 husky 的自检脚本放在pre-commit中：
npx --no-install husky --help >/dev/null 2>&1 || (echo "husky not ready, run npm install first" && exit 1)不过实际项目中很少这样写，因为prepare脚本已经保证了husky install在装依赖时执行。真到了需要排查的时候，我都是先跑：
npx husky init git config core.hooksPath ls -la .husky/三步确认环境，再谈别的。
最后分享一个我踩过不少次才悟出来的配置：如果有多个工具同时处理同一批文件，不要让两个命令都同时写文件。比如 esbuild-era 的人习惯prettier --write之后再跑eslint --fix，两个工具都改文件，lint-staged 自动 add 时会因为文件内容不断变化而多跑几轮。合理的做法是尽量让 prettier 收尾，因为它最尊重配置、输出稳定。如果 eslint 的 fix 和 prettier 顺序相反，有时会产生需要 commit 两次才能稳定下来的情况。这倒不是 bug，而是两个工具对格式化决策的迭代关系不同。
工具链的价值不在于把 hook 配得多全，而在于让"提交代码"这件事变成一个自动化的、无感的动作。Husky 和 lint-staged 这对搭档，本质上是把人工记忆强制变成了流程防线。你可以放心地把精力放在写业务上，剩下那些回车键前面的检查，交给它们就好。
