pre-commit钩子需显式安装且配置正确才生效：必须在git仓库根目录运行pre-commit install，确保.pre-commit-config.yaml语法无误（严格yaml格式），并验证.git/hooks/pre-commit为可执行文件；配置错误将导致静默跳过检查。
Pre-commit 钩子不是装完 pre-commit 库就能自动生效的，它必须被显式安装到 Git 的 hooks 目录里，且配置文件 .pre-commit-config.yaml 必须存在并语法正确——否则 git commit 时完全不会触发任何检查。
如何初始化 pre-commit 并确保钩子真正挂载到本地仓库
很多人执行了 pre-commit install 却发现提交没反应，常见原因是：当前目录不是 Git 仓库根目录，或未在项目根目录下运行该命令。Git hook 只对当前仓库生效，不能跨项目复用。
- 进入项目根目录（即包含
.git和.pre-commit-config.yaml的目录） - 运行
pre-commit install—— 它会把脚本复制到.git/hooks/pre-commit - 验证是否成功：
ls .git/hooks/pre-commit应输出一个非空可执行文件 - 若已存在旧 hook（比如手动写的 shell 脚本），
pre-commit install默认不覆盖，需加--overwrite
为什么 .pre-commit-config.yaml 格式错一行就全失效
pre-commit 解析配置时严格遵循 YAML 规范，缩进错误、漏掉冒号、键名拼错都会导致 pre-commit run 报 Invalid config: ...，且 git commit 会直接跳过所有检查（静默失败，不是报错中断）。
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 必须用空格缩进，禁止 Tab；
repos下每个- repo:块顶格，内部rev、hooks等字段缩进 2 空格 - 钩子名称（
id）必须与所选 repo 官方定义一致，比如black不能写成black-format - 修改配置后要运行
pre-commit autoupdate更新rev，否则可能拉不到最新版，尤其当 repo 使用main分支时
pre-commit run --all-files 和 git commit 的行为差异
pre-commit run --all-files 是手动全量扫描，而 git commit 默认只检查暂存区（staged）文件。这会导致“本地测试通过但 CI 失败”——因为 CI 通常跑的是 --all-files 或指定路径。
- 开发时建议定期执行
pre-commit run --all-files，尤其在改完配置或新增文件后 - 若想让
git commit也扫全部文件（不推荐日常用），可加--hook-stage=manual参数，但更合理的是在 CI 中统一用--all-files - 某些 hook（如
check-yaml）默认只处理.yaml和.yml，但如果你有.pre-commit-config.yaml本身格式错误，它反而不会被检查——得靠人工或编辑器插件提前兜底
最容易被忽略的是 hook 的语言运行时依赖：比如 black 需要 Python 3.8+，eslint 需要 Node.js，而 pre-commit 默认为每个 repo 创建独立虚拟环境，但它不会帮你装系统级依赖。如果某个 hook 报 command not found，先确认对应解释器是否已在 $PATH 中，而不是急着重装 pre-commit。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
