pre-commit：一套框架管好所有 Git 提交检查

pre-commit 在 GitHub 上已经拿到 15,300 Star 了。

这个工具解决了一个团队开发中反复出现的问题：代码在提交之前有没有跑过 lint、格式化、类型检查？手动执行太容易忘，推到 CI 上才发现又太晚了。pre-commit 把检查前置到 git commit 那一刻，不通过就不让提交。

一句话：管理和维护 Git pre-commit hooks 的框架。

pre-commit 本身不是 lint 工具，它是 lint 工具的调度器。你告诉它「提交 Python 代码前跑 black 和 flake8，提交 JS 代码前跑 eslint」，它就会在每次 git commit 时自动拉起这些工具，只检查本次修改的文件，不会全量扫描。

写过 CI 流水线的人都清楚，等代码推到远程再发现格式问题是什么体验：改完重新 push，触发新一轮 CI，同事收到通知，review 被打断。来回几次，一天就过去了。

pre-commit 把反馈提前到本地。不通过检查，commit 根本创建不了。问题在本地就解决了，不会进仓库。

另一个好处是配置集中在 .pre-commit-config.yaml 一个文件里。新成员 clone 仓库后跑一次 pre-commit install，团队统一的检查规则就生效了，不需要每个人手动装各种工具、对齐版本号。

pre-commit 的配置围绕三个概念展开：

hooks：要执行的检查。可以是一个 shell 命令、一个 Python 脚本，或者任意可执行程序。不限语言。

repos：hooks 的来源。每个 repo 指向一个 Git 仓库，pre-commit 会自动拉取对应版本的代码，在隔离环境中运行。

stages：hooks 的执行时机。默认在 commit 阶段触发，也可以配置到 push、merge-commit、prepare-commit-msg 等阶段。

hooks 可以用社区维护的现成方案，比如 black、ruff、eslint 对应的 hook。团队也可以自己写 hook，放在项目的某个目录里，pre-commit 一样能管。

安装只需要 pip：

bash 复制代码

pip install pre-commit

在项目根目录创建 .pre-commit-config.yaml，声明要用哪些 hooks，指定版本号。然后装到 Git hooks：

bash 复制代码

pre-commit install

之后每次 git commit 都会自动运行配置的检查。想手动跑一遍全部文件做存量修复：

bash 复制代码

pre-commit run --all-files

pre-commit 会自动管理各个 hook 的运行环境。用 Python 的 hook 它拉 Python 环境，用 Node 的拉 Node 环境，互不干扰。更新 hook 版本也只是一条命令：

bash 复制代码

pre-commit autoupdate

Python 项目维护者：社区里 pre-commit 的使用率很高，.pre-commit-config.yaml 几乎成了 Python 项目的标配文件。

多语言团队的 Tech Lead：一套配置管好 Go、Python、JS、Rust 的提交检查，不用在每个语言生态里重复造轮子。

开源项目维护者：降低贡献者的提交门槛。规则写在配置里，贡献者不需要手动记格式要求，pre-commit 在本地就会拦住不合规的提交。