pre-commit 不支持真正的全局钩子，因其设计要求钩子版本、配置和依赖必须与项目代码一起受控以保证可重现性；所谓“全局”需通过复用配置文件+自动化脚本模拟，否则易导致钩子失效、CI失败或提交被阻断。
不能直接配置“全局” pre-commit 钩子——pre-commit 本身不支持真正的全局安装或全局生效，所有钩子必须按项目声明并本地安装。 所谓“全局”，实际是通过复用配置 + 自动化脚本模拟，但误配反而会导致钩子不触发、CI 失败或本地提交被意外阻断。
为什么 pre-commit 不允许全局钩子
pre-commit 的设计哲学是：钩子版本、配置、依赖必须与项目代码一起受控。不同项目可能需要 black==22.3.0 或 black==24.8.0，甚至禁用某条规则；全局统一会破坏可重现性。官方明确不提供 pre-commit install --global，强行软链或修改用户目录 hook 模板极易失效（尤其在 Git 多版本、WSL、IDE 集成等场景）。
用 .pre-commit-config.yaml + 脚本实现“类全局”管理
核心思路：把通用配置抽成独立 YAML 文件，用脚本自动同步到各项目，并确保每次 git commit 前都运行 pre-commit install（避免漏装）。
- 在
~/.config/pre-commit/base-config.yaml存放你的标准配置（含repos、default_stages等），但**不包含exclude或项目特有正则** - 在项目根目录写一个
setup-pre-commit.sh（或setup-pre-commit.py），内容为：cp ~/.config/pre-commit/base-config.yaml .pre-commit-config.yaml<br>pre-commit install --hook-type pre-commit --hook-type pre-push
- 运行该脚本后，再执行
pre-commit run --all-files验证是否生效；注意检查输出中是否出现[INFO] Installing environment for ...—— 若没有，说明钩子根本没加载
常见失效原因和验证方法
即使配置文件存在且 pre-commit install 成功，钩子仍可能静默不运行：
立即学习“Python免费学习笔记（深入）”；
-
git commit时无任何 pre-commit 输出？先确认当前目录下是否存在.git/hooks/pre-commit，且其内容是否以#!/usr/bin/env bash开头并调用pre-commit—— 如果是空文件或残留旧 hook，手动删掉再pre-commit install - 报错
Failed to detect the current Python interpreter？说明pre-commit启动时找不到 Python 环境，尤其在 pyenv、conda 或 VS Code 终端里；用which python检查路径，必要时在.pre-commit-config.yaml中显式指定language_version: python3.11 - 钩子只对部分文件生效？检查
files:和types:是否冲突，例如types: [python]会忽略.pyi文件，而files: \.pyi?$可覆盖它
真正麻烦的不是配置一次，而是当团队成员拉新项目、切换分支或重装系统后，pre-commit install 这一步总被跳过。最稳妥的做法，是在 Makefile 或 pyproject.toml 的 [tool.poetry.scripts] 里封装 setup-hooks 命令，并写进 CONTRIBUTING.md 第一行。否则，你永远不知道哪次 PR 是靠运气没带 bug 提交的。
