lint-staged不执行的根本原因是husky未生效，需确认.husky/目录存在、pre-commit文件内容为npx lint-staged、钩子具备可执行权限，且npm/pnpm环境下命令能正确解析本地依赖。
为什么 lint-staged 不执行？检查 husky 初始化是否成功
lint-staged 本身不监听 Git 事件，它必须由 Husky 的钩子（如 pre-commit）触发。如果提交时没反应，大概率是 Husky 没生效。
- 运行
npx husky-init或npx husky install后，确认项目根目录下生成了.husky/文件夹 - 检查
.husky/pre-commit文件是否存在，内容是否为类似npx lint-staged - 确保 Git 钩子可执行：在 Unix/macOS 上执行
chmod +x .husky/pre-commit；Windows 用户需确认 Git Bash 环境或使用 WSL - 若用 pnpm，
npx可能找不到本地依赖，改用pnpm exec lint-staged并同步更新.husky/pre-commit
lint-staged 配置只处理暂存文件，但实际格式化了整个文件？
这是 Prettier 默认行为：即使只传入变更行，prettier --write 仍会重写整文件。这不是 bug，而是设计使然 —— Prettier 不支持“局部重写”，它基于 AST 重建全文本。
- 想真正只改变更部分，得换工具（如 ESLint 的
--fix对部分规则支持行级修复，但非全部） - 若目标是提速，可在
package.json的lint-staged配置中排除大文件："*.{js,ts,jsx,tsx}": ["prettier --write"]，不要写成"**/*" - 注意：lint-staged 传给命令的是“暂存文件路径列表”，不是 diff 内容；它不负责 diff 计算，Git 才是源头
Node 环境下 lint-staged 报错 “Cannot find module ‘xxx’”
常见于 CI 或新 clone 仓库后首次提交 —— lint-staged 运行时找不到本地安装的 prettier 或 eslint，因为 Node.js 的 require.resolve() 机制依赖 node_modules 存在且路径正确。
- 确保
package.json中lint-staged的脚本命令明确指向本地二进制：用"prettier --write"而非"npx prettier --write"（后者可能 fallback 到全局） - CI 环境中若禁用
node_modules缓存，需在pre-commit钩子前加npm ci或pnpm install --no-frozen-lockfile - Windows 用户注意路径分隔符问题：避免在配置中硬编码
./node_modules/.bin/prettier，优先走 npm script 或 npx
如何让 lint-staged 和 VSCode 保存格式化不冲突？
两者都做格式化，容易导致保存时修一遍、提交前又修一遍，尤其当 Prettier 和 ESLint 规则有重叠（如引号、分号）时，可能引发“格式化抖动”。
- VSCode 侧建议关掉
editor.formatOnSave，或仅对非团队协作文件启用（如"[json]": { "editor.formatOnSave": true }） - 统一交由 lint-staged 处理：在
package.json中配"*.{js,ts}": ["eslint --fix", "prettier --write"]，并确保 ESLint 的rules和 Prettier 配置不冲突（推荐用eslint-config-prettier关闭所有格式类规则） - 关键点：
eslint --fix必须放在prettier --write前面，否则 Prettier 会覆盖 ESLint 的修复结果
