pre-commit 是什么
pre-commit 是提交前钩子框架：在仓库根目录写 .pre-commit-config.yaml 声明要跑的检查，框架负责创建隔离环境、缓存依赖，并默认只处理将要提交的文件。它把格式化与轻量检查前移到本地，让流水线不必再为空格和未使用导入这类问题浪费时间。
基本信息
| 配置文件 | .pre-commit-config.yaml |
|---|---|
| 运行时机 | git commit 之前，也可手动执行 |
| 运行范围 | 默认只处理将要提交的文件 |
| 环境隔离 | 每个仓库独立环境，按语言安装钩子依赖 |
典型使用场景
- 新项目初始化：一次安装钩子，全团队走同一套检查
- 格式化前移：Black、clang-format 之类在提交前就地修好
- 基础卫生清理：行尾空白、文件末尾换行、合并冲突标记
- 轻量安全检查：密钥扫描这类秒级检查适合放在这里
- 存量项目：先只装少量快钩子，避免提交过程变得难以忍受
哪些检查适合放钩子
- 秒级完成的格式化与清理类检查
- 只需要读改动的检查，例如密钥扫描
- 能在本地自动修复的问题
- 重型检查与全量测试仍然留给 CI
配置示例
配置示例
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0 # 版本固定，避免行为漂移
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-merge-conflict
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.6.9
hooks:
- id: ruff
- id: ruff-format常用命令
| 命令 | 作用 |
|---|---|
| pre-commit install | 安装 git 钩子 |
| pre-commit run --all-files | 对全部文件跑一遍 |
| pre-commit run --files a.py | 只跑指定文件 |
| pre-commit autoupdate | 更新钩子版本 |
钩子只跑快检查：全量测试与完整构建留给 CI，否则开发者会用跳过选项绕开整个钩子。
在评审中的用法：钩子跑过之后，评审者不必再提醒空格与导入顺序，注意力可以留给设计与边界条件。
钩子版本写在配置里并由框架缓存环境：团队成员不需要各自安装工具，环境差异造成结论不同的情况也会减少。
钩子太慢：开发者开始带跳过参数提交，钩子形同虚设。