这种”靶向式”检查方式，直接砍掉了全量扫描的90%冗余耗时：原本需要10分钟的全量检查，用Lint-Staged可能1分钟内就能完成，提交效率肉眼可见地翻倍。尤其在大型项目中，随着代码库体积增长，这种效率提升会更加明显。
本文将从实战角度，带你掌握Lint-Staged的核心用法：从基础配置（如何搭配ESLint、Prettier实现自动化检查），到进阶优化（忽略特定文件类型、自定义检查规则链），再到避坑指南（解决暂存区文件识别异常、检查结果与IDE不一致等问题）。无论你是前端开发还是全栈工程师，学会这套技巧，就能让代码检查从开发流程中的”等待负担”，变成提升协作效率的”隐形助手”。
你有没有试过这样的场景：周五下午快下班时，你急着提交一周改好的bug修复，结果执行npm run lint后，控制台开始滚动成百上千个文件的检查结果——明明你只改了3个文件，却要等5分钟看完全部项目的Lint报告？我去年在一个百人协作的React+TypeScript项目里就天天遇到这种事，当时全量Lint检查平均耗时12分钟，有次同事改了一行注释，硬生生等到咖啡凉透才提交成功。后来我们引入Lint-Staged做增量检查，同样的提交操作直接压缩到45秒，整个团队的提交频率从每天人均3次提升到6次，开发节奏明显快了起来。
为什么全量Lint检查正在拖慢你的开发效率
要理解Lint-Staged的价值，得先搞清楚传统全量检查到底“坑”在哪里。我见过不少团队把“执行全量Lint”设为提交代码的硬性要求，觉得这样能保证代码质量，但实际上这种“一刀切”的方式藏着三个致命问题。
第一个问题是冗余检查浪费90%的时间。我去年帮一个电商项目做工程化优化时，统计过他们的Lint耗时分布：项目里有800个JS/TS文件，每次全量检查中，真正被修改的文件平均只有5-8个，却要扫描全部800个文件。更夸张的是，其中60%的时间花在检查node_modules里的依赖文件（虽然配置了忽略，但某些Lint工具默认会扫描软链接文件），20%时间在检查三年前就没动过的历史代码。这种“为了1%的改动检查100%的代码”的模式，本质上是拿开发时间换心理安慰。
第二个问题是多人协作时的“等待连锁反应”。想象一下：你和同事同时改了不同模块的代码，你先提交时触发全量检查，等了10分钟；同事提交时，因为你的代码已经合并，全量检查又要重新跑10分钟——两个人一天提交5次，就有100分钟浪费在互相等待上。我之前带的团队就因为这个问题，把每日站会时间从早上9点推迟到10点，就为了等大家提交完代码，现在想想真是本末倒置。
第三个问题是错误信息淹没导致漏检。全量检查会输出成百上千行日志，你改的文件的错误可能混在几十条“未修改文件的陈旧警告”里被忽略。我见过最离谱的一次：一个同事提交代码时，全量Lint报了238条警告，他以为都是旧问题直接提交了，结果上线后发现自己改的文件里有个console.log没删——因为那条警告被其他237条信息挤到了控制台最上面，他根本没看到。
为什么会出现这些问题？核心原因是传统Lint工具（比如ESLint、StyleLint）默认“面向项目”而非“面向变更”。它们设计的初衷是确保整个项目符合规范，但没考虑到“开发过程中99%的提交都是小范围改动”这个实际场景。就像你家里只脏了厨房，却要把客厅、卧室、卫生间全打扫一遍，纯属浪费精力。
Lint-Staged实战：从配置到优化的全流程指南
既然全量检查这么低效，那Lint-Staged是怎么做到“只检查修改文件”的？简单说，它的核心逻辑是“盯住Git暂存区”——当你执行git add把文件加入暂存区后，Lint-Staged会读取暂存区列表，只对这些文件执行检查命令。这种“靶向打击”的思路，直接砍掉了全量检查的冗余环节。下面我结合自己5个项目的落地经验，带你从0到1掌握它的实战技巧。
基础配置：3步实现“暂存区文件自动检查”
配置Lint-Staged其实比你想象的简单，哪怕你是刚接触工程化的新手，跟着这三步走也能10分钟搞定。
第一步是安装核心依赖。你需要先安装Lint-Staged本身，以及Git Hooks工具（推荐husky，用来在提交前触发检查）。打开终端输入这行命令：
npm install save-dev lint-staged husky这里有个小细节：如果你的项目用pnpm，记得加shamefully-hoist参数，避免依赖路径问题导致husky钩子不生效——我之前在一个Vue3项目里就踩过这个坑，折腾了两小时才发现是pnpm的依赖隔离导致的。
第二步是配置husky钩子。现在需要让Git在执行git commit时自动触发Lint-Staged。先启用husky：
npx husky install
npx husky add .husky/pre-commit "npx lint-staged"
这行命令会在.husky/pre-commit文件里添加钩子脚本，意思是“提交前先运行lint-staged”。如果你想验证钩子是否生效，可以运行npx husky list，能看到pre-commit钩子已被注册。
第三步是定义Lint-Staged规则。在package.json里添加lint-staged字段，告诉它“哪些文件需要检查”以及“用什么命令检查”。比如你用ESLint检查JS/TS文件，用Prettier格式化代码，可以这样写：
{
"lint-staged": {
".{js,jsx,ts,tsx}": ["eslint fix", "prettier write"],
".{css,scss}": ["stylelint fix", "prettier write"],
".{md,json}": ["prettier write"]
}
}
这里的键".{js,jsx,ts,tsx}"表示“暂存区中所有符合这些后缀的文件”，值是要依次执行的命令：先用eslint fix自动修复可修复的错误，再用prettier write格式化代码。为什么要加fix和write？因为Lint-Staged不仅能检查错误，还能帮你自动修复，省去手动改格式的时间——我之前在一个React Native项目里，光是自动修复缩进和引号格式，每周就能省出2小时。
配置完成后，你可以这样测试：修改一个JS文件后执行git add，再运行npx lint-staged，会看到控制台只输出你修改的那个文件的检查结果。如果没问题，直接git commit就能触发自动检查，有错误会阻止提交，直到你修复为止。
进阶优化：让Lint-Staged效率再提升50%的3个技巧
基础配置能解决大部分问题，但在大型项目里，你可能会遇到“暂存区文件太多导致检查还是慢”“特定文件不需要检查”等情况。这时候就需要进阶优化，我 了三个亲测有效的技巧。
技巧一：按文件大小分级检查
。如果你的项目里有超大文件（比如超过1000行的配置文件），即使只改了一行，Lint检查也会很慢。你可以用glob语法匹配文件大小，给大文件设置简化规则。比如在lint-staged配置里加：
{
"lint-staged": {
".{js,ts}": [
// 小文件用完整规则
(filenames) => filenames.filter(f => fs.statSync(f).size eslint fix ${f}),
// 大文件只检查语法错误，跳过风格检查
(filenames) => filenames.filter(f => fs.statSync(f).size >= 1024 100).map(f => eslint fix no-eslintrc parser-options=ecmaVersion:2020 ${f})
]
}
}
这里用Node的fs.statSync判断文件大小（100KB为界），大文件跳过自定义规则（no-eslintrc），只保留基础语法检查，我在一个有30个超大配置文件的中台项目里用这个方法，大文件检查耗时从2分钟降到20秒。
技巧二：组合“检查-修复-提交”一条龙
。有时候你改完代码只想快速提交，不想手动add和commit。可以用lint-staged搭配git commit -am，但更优雅的方式是用simple-git-hooks替代husky（更轻量），并在package.json里加脚本：
{
"scripts": {
"commit": "git add . && lint-staged && git commit"
}
}
这样执行npm run commit就能自动把所有修改文件加入暂存区、检查修复、提交，省去三步操作。我带的团队现在都用这个脚本，提交效率又提升了30%。
技巧三：忽略“只改注释/空格”的文件
。有些修改（比如给函数加注释、调整空行）其实不影响代码逻辑，没必要跑完整Lint。你可以用git diff name-only diff-filter=M筛选“内容修改”的文件（排除只改权限或重命名的文件），再传给Lint-Staged。具体实现需要写个Node脚本（保存为scripts/filter-files.js）：
const { execSync } = require('child_process');
const filenames = process.argv.slice(2);
// 只保留内容被修改的文件
const modifiedFiles = execSync('git diff name-only diff-filter=M').toString().trim().split('n');
// 输出交集
console.log(filenames.filter(f => modifiedFiles.includes(f)).join(' '));
然后在lint-staged配置里引用这个脚本：
{
"lint-staged": {
".{js,ts}": [
"node scripts/filter-files.js",
"eslint fix"
]
}
}
这个技巧在多人协作时特别有用，能过滤掉70%的“无效检查”，我去年在一个教育平台项目里用它，每月减少了12小时的等待时间。
避坑指南：90%的人会踩的3个配置陷阱
就算按上面的步骤配置，你可能还是会遇到“检查不生效”“IDE和Lint-Staged结果不一致”等问题。这些坑我都踩过，这里分享解决方案。
陷阱一：暂存区文件识别失败，提示“没有文件需要检查”
。这通常是因为你没把文件加入暂存区就提交了。比如你改了index.js，直接git commit -m "fix"，这时候暂存区是空的，Lint-Staged自然没文件可检查。解决办法是养成git add后提交的习惯，或者用前面说的npm run commit脚本自动add。 陷阱二：ESLint规则和IDE配置冲突。比如你在VSCode里用Prettier插件格式化了代码，但Lint-Staged用的Prettier配置文件是.prettierrc，导致提交时又被改回去。解决办法是统一配置源：在项目根目录放.prettierrc和.eslintrc，并在VSCode设置里开启“保存时用Prettier格式化”，确保IDE和Lint-Staged用同一套规则。 陷阱三：Windows系统下路径空格导致命令报错。如果你的项目路径有空格（比如C:My Projectapp.js），Lint-Staged可能会把路径拆成两个参数。解决办法是在命令里给文件路径加引号，比如用eslint fix "${f}"替代eslint fix ${f}（需要在配置里用函数形式）：
{
"lint-staged": {
".js": (filenames) => filenames.map(f => eslint fix "${f}")
}
}
这个问题我在帮一个Windows用户配置时遇到过，当时排查了两小时才发现是路径空格的锅。
最后想对你说：Lint-Staged不是银弹，它的核心价值是“让工具适应开发流程，而不是反过来”。我见过有些团队为了“100%规范”把Lint规则设得极其严格，结果Lint-Staged检查时间反而比全量还长——这就本末倒置了。真正的工程化优化，应该是“在质量和效率间找平衡”：用Lint-Staged减少等待，用自动化修复降低人工成本，把省出来的时间花在更有价值的功能开发上。
如果你按上面的步骤配置后，发现提交效率真的提升了，欢迎在评论区告诉我你的项目规模和效率提升百分比；如果遇到问题，也可以留言具体场景，我会尽量帮你排查。 好的工具应该让开发更轻松，而不是更麻烦，对吧？
（注：本文Lint-Staged配置方法参考了其GitHub官方文档{rel=”nofollow”}，ESLint与Prettier组合方案参考了Frontend Masters的工程化课程{rel=”nofollow”}）
你是不是刚配置好Lint-Staged，兴冲冲地改了代码，直接敲git commit -m 'fix: 修复登录按钮样式'，结果控制台蹦出一句“没有文件需要检查”？当时是不是一脸懵——明明改了好几个文件，怎么会没文件可检查呢？其实这事儿我上周还帮实习生排查过，他就是犯了个新手常犯的错：忘了把修改的文件“告诉”Git。
Lint-Staged的脾气很“倔”，它只认Git暂存区里的文件——就是那些你用git add命令标记过的文件。你想啊，Git管理代码的时候，有工作区、暂存区、本地仓库三个地方，你改完代码存在工作区，得用git add把它们“挪”到暂存区，Git才知道“这些是我要提交的内容”。Lint-Staged就是盯着暂存区干活的，要是暂存区是空的，它自然就两手一摊：“没文件让我检查啊！”就像你去食堂打饭，得先把餐盘放到窗口前，师傅才知道要给你打菜，总不能举着空碗站那儿等吧？
那咋解决呢？最简单的办法就是养成“先add再commit”的习惯。改完代码后，先敲git add 文件名（比如git add src/components/LoginButton.vue），把要提交的文件加入暂存区，再执行git commit，这时候Lint-Staged就会乖乖检查这些文件了。要是你改的文件多，一个个add麻烦，也可以用git add .把所有修改文件一次性加入暂存区，再commit就好。
不过我更推荐你配个自动脚本，一步到位。在package.json的scripts里加一行："commit": "git add . && lint-staged && git commit"，保存后，以后改完代码直接敲npm run commit，它会自动帮你把所有修改文件加入暂存区、跑Lint-Staged检查、弹出提交信息输入框，全程不用手动敲好几个命令。我自己的项目里就这么配的，现在提交代码就跟喝水一样自然，再也没忘过add这一步。
对了，还有个小细节要注意：如果你用了像SourceTree、GitKraken这类图形化工具，记得提交前先在工具里把文件“暂存”（一般是勾选文件前面的复选框），原理和命令行git add是一样的。工具界面上通常会标“暂存区”和“未暂存区”，确保你要提交的文件在暂存区里，Lint-Staged才会正常工作。试过一次你就知道，这问题解决起来其实特简单，就是一层窗户纸，捅破了就再也不会踩坑了。
Lint-Staged只适合大型项目吗？小项目有必要用吗？
并非只适合大型项目。小项目（如100个文件以内）使用Lint-Staged能减少50%-70%的检查时间（比如全量检查2分钟缩短到30秒内），虽然绝对耗时差异不大，但能避免“改一行代码等半分钟”的打断感；大型项目（500个文件以上）收益更明显，全量检查10分钟可压缩到1分钟内，尤其多人协作时能避免等待连锁反应，所以无论项目大小，只要需要频繁提交代码，都值得配置。
Lint-Staged能和ESLint、Prettier一起用吗？如何配置组合检查？
完全可以，且推荐组合使用。基础配置时，在package.json的lint-staged字段中，为不同文件类型指定检查命令即可，比如：”.{js,ts}”: [“eslint fix”, “prettier write”]，这样会先通过ESLint修复代码规范问题，再用Prettier格式化代码格式，实现“规范检查+格式统一”一条龙处理，无需手动执行多个命令。
配置Lint-Staged后，为什么提示“没有文件需要检查”？
这通常是因为文件未加入Git暂存区。Lint-Staged仅检查Git暂存区（git add后的文件），如果直接执行git commit而未先git add，暂存区为空，就会出现该提示。解决办法：提交前先用git add将修改文件加入暂存区，或配置npm脚本自动执行“git add . && lint-staged && git commit”，实现“修改-检查-提交”一键完成。
使用Lint-Staged会影响代码质量吗？会不会漏掉未修改文件的问题？
不会影响代码质量，也不会漏掉关键问题。Lint-Staged只优化“检查范围”，不改变检查规则——修改文件的代码规范仍会被严格检查，未修改文件的历史问题可通过定期全量检查（如每周一次）或CI流程兜底。实际项目中，结合“增量检查（日常提交）+ 全量检查（合并主分支前）”的模式，既能保证效率，又能避免历史问题积累。
