VSCode 配合 Git Hook 实现提交前代码运行自动校验

在 VSCode 里配置 Git Hook 实现提交前自动代码校验，听起来很简单，但实际踩坑的人不少。要么钩子压根不触发，要么修复了代码却没被暂存，要么点一下 VSCode 的提交按钮直接跳过所有检查。问题出在哪？我们来逐一拆解。

pre-commit钩子不触发主因是husky未安装、.husky/pre-commit无执行权限或lint-staged缺失；VSCode点提交无反应因git.enableSmartCommit=true绕过钩子，需设为false并确保git add在lint-staged命令末尾。

pre-commit 钩子不触发，大概率是 husky 没装好或权限不对

很多人以为在 VSCode 点了提交按钮，钩子就能自动跑。真实情况是，.git/hooks/pre-commit 根本没被执行。原因不外乎三个：

• npx husky install 没跑过，.husky/ 目录压根不存在
• .husky/pre-commit 文件存在但缺少可执行权限（macOS/Linux 下必须手动 chmod +x .husky/pre-commit）
• 项目根目录没有 package.json，或者 lint-staged 没装在 devDependencies 里，导致 npx lint-staged 命令找不到

哪一环断了，校验就静默失效。排查时按这个顺序逐一确认，基本能定位问题。

lint-staged 配置里漏掉 git add，修复就白做了

很多人配置了 eslint --fix 和 prettier --write，以为修复完就万事大吉。实际上它们只改了工作区文件，不会自动重新暂存。如果 lint-staged 的配置里没有显式加上 "git add"，那么修复后的代码根本不会被纳入本次提交——你看到的提交内容还是旧版本，CI 或队友拉下来照样报错。

正确写法示例：

"*.{js,ts}": ["eslint --fix", "prettier --write", "git add"]

注意顺序很关键：git add 必须放在最后。否则 prettier 改完还没来得及暂存，eslint 可能又报出新错误，导致命令链中断。

VSCode 的 git.enableSmartCommit 会绕过 pre-commit

这个选项默认是 true，它的作用是让 VSCode 把“未暂存的修改”直接塞进 commit，跳过 Git 原生的 pre-commit 流程。结果就是：你在终端里 git commit 能触发 lint，但 VSCode 上点 ✔️ 却秒提成功——钩子根本没被调用。

解决方法很简单：

• 打开 VSCode 设置（Cmd+, 或 Ctrl+,）
• 搜索 git.enableSmartCommit
• 把它设为 false

之后必须手动 git add 再提交，才能确保钩子生效。这一步很多人忽略，却是最隐蔽的坑。

VSCode 的 eslint.autoFixOnSa ve 和 pre-commit 冲突

两者都修改工作区文件，但时机和范围不同：

• autoFixOnSa ve 是每次保存都全量扫描当前文件
• pre-commit 只处理暂存区中带 --fix 的文件

同时开启时，容易出现“保存时修了一次，提交前又修一次”，导致工作区和暂存区内容不一致，git diff 里出现一堆无关变更。混乱的根源就在这里。

建议做法：

• 关掉 eslint.autoFixOnSa ve（无论是在全局设置还是项目级设置）
• 把格式化和修复逻辑完全交给 pre-commit + lint-staged 统一管控，这样流程清晰，也不容易出岔子

真正起作用的从来不是 VSCode 界面按钮，而是 .husky/pre-commit 脚本是否被 Git 正确加载、Node 环境是否可用、以及暂存区文件是否真的被 lint-staged 拿到并处理——这些环节任何一个断掉，自动校验就成摆设。