.pre-commit-config.yaml 必须放在项目根目录，文件名严格为该名称且后缀为 .yaml；rev 字段须填确定的 commit hash 或 tag，不可用分支名；python hooks 需显式声明 language_version；运行时应指定 --hook-stage pre-commit 以匹配 git commit 行为。
pre-commit 配置文件写在哪、叫什么名
必须叫 .pre-commit-config.yaml，且必须放在项目根目录。不是 pre-commit-config.yaml，也不是 .pre-commit-config.yml——虽然 YAML 规范允许 .yml，但 pre-commit 工具只认 .yaml 后缀，否则会静默忽略配置。
常见错误现象：pre-commit install 成功，但提交时 hooks 完全不触发；或者 pre-commit run --all-files 报错 No config file found。
- 检查路径：运行
ls -a确认文件存在且名字拼写完全一致 - 确认缩进：YAML 对空格敏感，
repos:必须顶格，每个 hook 的id:和rev:必须对齐且用空格（不能用 Tab） - Windows 用户注意：编辑器可能默认保存为 UTF-8 with BOM，会导致解析失败；建议用 VS Code 或 Notepad++ 显式选 “UTF-8 no BOM”
hooks 里 rev 字段填什么、为什么不能写 latest
rev 必须填确定的 Git commit hash 或 tag（如 v4.3.0），不能写 latest、main 或 master。因为 pre-commit 会在本地克隆仓库并 checkout 到该 rev，如果填分支名，每次运行都可能拉到不同代码，破坏可重现性——CI 和同事的环境结果就不一致。
使用场景：团队协作、CI 流水线、代码审查前自动检查。
立即学习“Python免费学习笔记（深入）”；
- 查可用 tag：访问对应 hook 仓库的 GitHub Releases 页面，例如
pre-commit-hooks在 https://www.php.cn/link/403e7163b5aef0323eee42fe413bccc5 - 别盲目升级：比如把
rev: v4.2.0改成v4.3.0前，先本地跑pre-commit run --all-files，确认没新增误报或破坏性变更 - 某些 hook（如
pylint）需要额外安装依赖，rev不匹配会导致hook failed (return code 1)且无明确提示
Python hooks（如 black、isort、pylint）怎么指定 Python 版本
靠 language_version 字段控制，不是靠系统默认 Python 或 virtualenv。它告诉 pre-commit 用哪个版本的 Python 解释器来运行 hook，直接影响语法兼容性（比如用了 := 海象运算符，就得设 language_version: python3.8+）。
常见错误现象：black 报 SyntaxError: invalid syntax；pylint 检出大量 undefined-variable，实际是类型提示里用了新语法但解释器太老。
- 推荐显式声明：在每个 Python hook 下加
language_version: python3.11（和项目pyproject.toml里要求的一致） - 不要依赖
default_language_version全局设置——它只对未声明language_version的 hook 生效，容易漏掉 - 如果 hook 自身不支持目标 Python 版本（比如旧版
pylint不支持 3.12），pre-commit会在 install 阶段报错Failed to install environment，需降级rev或换工具
pre-commit run 和 git commit 触发行为不一致怎么办
根本原因是：git commit 走的是 pre-commit 的「pre-commit」stage，而 pre-commit run 默认走的是「commit」stage，但很多 hook（尤其是 lint 类）只注册在「pre-commit」stage。所以手动 run 时没报错，commit 却卡住。
性能影响：重复执行 hook 会拖慢提交速度；stage 错配则导致检查失效，失去意义。
- 查 hook 注册 stage：看其文档或源码里的
entry和types，例如black默认只在pre-commit，check-yaml可在多个 stage - 强制 stage 匹配：运行
pre-commit run --hook-stage pre-commit --all-files模拟真实提交流程 - 调试技巧：加
-v参数，比如git commit -m "test" -v，能看到具体哪个 hook 被调用、传了哪些文件、返回码多少
最常被忽略的是：.pre-commit-config.yaml 里某个 repo 的 hooks 列表里混进了只适用于其他 stage（如 pre-push）的 hook，却没删干净，导致 commit 时意外触发失败。
