pre-commit 是什么
pre-commit 是 Git 钩子的统一管理器：在 .pre-commit-config.yaml 里声明格式化、lint、密钥扫描等检查，安装后每次提交前自动运行；同一份配置可以在 CI 里复跑，防止本地 --no-verify 绕过。它把「提交前该干什么」从口头约定变成可版本管理的配置。
基本信息
| 配置 | .pre-commit-config.yaml 声明仓库、版本与钩子 |
|---|---|
| 安装 | pre-commit install 写入 git 钩子 |
| 全量运行 | pre-commit run --all-files |
| 闭环 | CI 中同样执行，防本地绕过 |
| 更新 | pre-commit autoupdate 升级钩子版本 |
| 选择 | 钩子要快而稳，大检查放 CI |
| 修复 | 钩子自动改文件后需要重新提交已修改内容 |
| 环境隔离 | 每个钩子用独立环境运行，互不干扰 |
配置示例
配置示例
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0 # 固定版本，保证一致性
hooks:
- id: end-of-file-fixer # 文件尾空行
- id: check-yaml # YAML 语法
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.0 # 密钥扫描
hooks:
- id: gitleaks典型使用场景
- 格式统一：代码格式化工具在提交前自动跑一遍
- 密钥拦截：gitleaks 等扫描阻止明文密钥入库
- 配置校验：YAML、JSON 语法错误提交前暴露
- CI 提速：本地拦掉低级错误，减少远端失败重跑
- 团队统一：新人克隆后一次 install 获得同一套检查
- 存量整改：run --all-files 对历史文件做一轮修复
- 多语言仓库：不同语言的钩子各用各的运行环境，无需在开发者机器上预装工具链
环节与落点
| 环节 | 命令或位置 | 作用 |
|---|---|---|
| 安装 | pre-commit install | 启用提交钩子 |
| 日常提交 | git commit | 增量检查改动文件 |
| 全量 | run --all-files | 全库检查 |
| 升级 | autoupdate | 更新钩子版本 |
| CI 复跑 | 流水线中执行 | 防止本地绕过 |
| 失败处理 | 修复后重新 add 与 commit | 自动修复也要进暂存区 |
本地钩子提升提交质量，CI 复跑保证一致性：两道都有才闭环。
只依赖本地钩子：--no-verify 或新机器未安装即可绕过。
钩子里跑全量测试：提交变慢后被禁用，选快速稳定的检查项。
自动修复类钩子改完文件要重新提交：不然修复只停留在工作区。
钩子首次运行会安装各自的运行环境：网络受限的环境要提前准备镜像源或缓存。