VSCode 与 pre-commit hooks 结合可实现提交前自动质量检查，不通过则无法提交；pre-commit 是 Python 编写的钩子管理工具，通过 .pre-commit-config.yaml 定义团队共享的本地检查规则，配合 VSCode 插件和统一格式化配置（如 black/ruff），确保编辑与提交规则一致，避免冲突。
VSCode 与 pre-commit hooks 结合，能让代码质量检查真正“落地”——不是靠人记、不是靠 CI 拦截，而是提交前自动触发，不通过就无法提交。
pre-commit 是什么，为什么需要它
pre-commit 是一个 Python 编写的钩子管理工具，它在 git commit 执行前运行指定的检查脚本（比如代码格式化、语法检查、安全扫描）。它不依赖编辑器，但和 VSCode 配合后，能实现“写完即查、提交即拦”的闭环体验。
关键点：
- 钩子定义在项目根目录的 .pre-commit-config.yaml 中，团队共享、版本可控
- 检查在本地运行，速度快、反馈及时，不上传未通过的代码
- 和 VSCode 的保存操作不直接绑定，但可通过插件或配置让“保存时格式化”与 pre-commit 工具链对齐，避免冲突
VSCode 中如何配合 pre-commit 使用
VSCode 本身不执行 pre-commit，但可通过以下方式无缝衔接：
- 安装 pre-commit 并初始化：在项目中运行 pip install pre-commit，再执行 pre-commit install —— 这会在 .git/hooks/ 下生成 commit-msg 和 pre-commit 脚本
- 推荐安装 VSCode 插件 Pre-commit（作者：cds-amal）：它能在状态栏显示钩子状态，点击可手动触发 pre-commit run，并高亮失败项
- 统一代码风格工具链：比如用 black 格式化、ruff 检查，确保 VSCode 的 “Format On Save” 也调用 black（通过 python.defaultInterpreter 和 python.formatting.provider 配置），避免保存后格式和 pre-commit 不一致
常见问题与避坑建议
很多团队卡在“配置了却没生效”或“和 VSCode 自动格式化打架”，核心是工具职责要分清：
- pre-commit 负责“守门”：只在 commit 前运行，不修改文件（除非用 --hook-stage manual 或配置 auto-fix 类 hook，如 ruff --fix）
- VSCode 的 Format On Save 负责“日常整理”：应和 pre-commit 使用同一套规则（例如都用 black + ruff），否则保存后代码“看起来正常”，一提交却报错
- 如果用了 ESLint（JS/TS），推荐用 eslint --fix 作为 pre-commit hook，并关闭 VSCode 的 ESLint 自动修复（或设为 on-save 且仅 fix 可安全修复的问题），防止重复或冲突
- 首次运行 pre-commit run 失败？常见原因是未安装对应语言环境（如 node/rust/python 包），按错误提示装好再重试即可
基本上就这些。VSCode 提供编辑体验，pre-commit 提供质量底线，两者对齐后，代码提交不再是“赌运气”，而是确定性动作。
