lint-staged的核心目标是仅对Git暂存区文件执行ESLint、Prettier、Stylelint等校验与修复，避免全量扫描；需在package.json中按文件类型精准配置命令，配合Husky pre-commit钩子自动触发，确保提交前代码质量。
Vue 3 项目初始化时配置 lint-staged，核心目标是只对 本次提交暂存区（staged）里的文件 做 ESLint、Prettier、Stylelint 等校验和自动修复，避免全量扫描拖慢提交流程。关键不在“装完就完”，而在于让 lint-staged 精准识别文件类型、调用对应工具、且不报错跳过非代码文件。
一、先确保基础工具已就位
lint-staged 本身不干活，它依赖其他工具执行具体任务。初始化前请确认：
- ESLint 已安装并能单独运行（如
pnpm eslint src/App.vue --fix成功） - Prettier 已安装，且与 ESLint 配置无冲突（推荐用
eslint-config-prettier关闭 ESLint 中与 Prettier 冲突的规则） - Stylelint（可选但推荐）已为
.vue和 CSS 类文件配置好 - 项目使用 pnpm（主流 Vue 3 工程实践），命令统一用
pnpm
二、安装并声明 lint-staged
执行安装命令：
pnpm add lint-staged -D
在 package.json 中添加配置段（注意不是脚本，是顶层字段）：
立即学习“前端免费学习笔记（深入）”；
将静态 Vue 页面(index.vue)改造为动态页面(Custom.vue)；稿源仅限 index.vue、其引用的 CSS 与资源路径，禁止参考仓库内其他文件。Invoke when user wants to transform a static Vue page into a dynamic data-driven page with Element UI components.
"lint-staged": {
"*.{js,ts,vue}": ["eslint --fix"],
"*.{css,scss,sass,less,postcss}": ["stylelint --fix"],
"*.{json,md,yml,yaml,html}": ["prettier --write"]
}
⚠️ 注意：
– 不要用 "*": ["pnpm run lint"] 这种写法，它会把 README.md、.gitignore 等全传给 ESLint，导致解析失败；
– 文件后缀用小写（.vue 而非 .Vue），避免 macOS/Linux 下匹配失败；
– 若项目含 .tsx 或 .jsx，需显式加入数组中。
三、接入 Husky 实现 pre-commit 自动触发
仅配 lint-staged 不会自动运行，需 Git Hook 触发。推荐用 Husky v8+（当前主流）：
- 安装 Husky：
pnpm add husky -D - 启用钩子：
npx husky install - 创建 pre-commit 钩子：
npx husky add .husky/pre-commit "pnpm lint-staged"
此时每次 git commit 前，都会自动执行 pnpm lint-staged，只处理你 git add 过的文件。
四、验证与避坑要点
完成配置后，做一次真实测试：
- 修改一个
.vue文件，故意加个 ESLint 报错（比如多一个空格或未使用变量） - 执行
git add src/App.vue - 运行
git commit -m "test lint-staged" - 观察终端输出：应看到 ESLint 自动 fix 并继续提交；若失败，检查控制台报错路径是否指向非 JS/TS/Vue 文件
常见问题：
-
“Parsing error: Invalid character” → 多因 lint-staged 匹配了
.md或.json给 ESLint 处理，检查配置中是否漏写了prettier分支，或误删了*.{json,md}规则 -
修改了 .scss 却没被 stylelint 处理 → 确认
lint-staged配置里包含scss后缀，且 stylelint 已正确安装并支持该语法 -
commit 被中断但没提示原因 → 在
.husky/pre-commit文件首行加set -e（Bash 默认行为），确保错误不静默忽略
