pre-commit 中文教程：5 个真实场景快速开始（2026 版）

pre-commit 中文实战教程:Python(black/ruff)、JavaScript(eslint/tsc)、YAML/JSON/TOML 语法校验、私钥防泄漏(gitleaks)、提交前跑测试,五个场景开箱配置。

发布于 2026-09-13·4500 字·首发地址

pre-commit 中文教程pre-commit 配置Git hooks代码质量gitleaksCI/CD

pre-commit 中文教程：5 个真实场景快速开始（2026 版）

本文基于 pre-commit（pre-commit/pre-commit，MIT License）实测整理，原创中文场景 demo。中文译注 + 原创 demo 版权归裕普网络有限公司所有。

一、pre-commit 是什么

git commit 是代码进入仓库的最后一道闸门，但绝大多数团队靠「自觉 + Code Review」把关——格式问题、调试语句、私钥泄露，总有人忘了检查。

pre-commit 的做法是把这个闸门自动化：它在 git commit 执行前拦截，跑一遍你配置好的检查钩子（hook），任何一项失败就拒绝提交。

pip install pre-commit          # 安装
pre-commit install              # 挂载到 git hooks（一次性）
git commit -m "xxx"             # 之后每次提交自动触发

三个关键认知：

配置即代码：所有检查项写在仓库根目录的 .pre-commit-config.yaml 里，团队成员 clone 后跑一次 pre-commit install 就有完全一致的门禁；
语言无关：hook 可以是 Python / Node / Go / Rust 写的任何可执行检查——一个配置管全栈仓库；
CI 可复用：同一份配置在 CI 里跑 pre-commit run --all-files，本地和远端规则永远一致。

二、5 分钟上手

# 1. 安装（Python 3.9+）
pip install pre-commit

# 2. 在仓库根目录创建 .pre-commit-config.yaml
cat > .pre-commit-config.yaml <<'EOF'
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
EOF

# 3. 挂载 + 首次全量跑
pre-commit install
pre-commit run --all-files

注意：首次运行会 clone hook 仓库到本地缓存（~/.cache/pre-commit），国内网络慢的话提前挂代理或用镜像。

三、场景 1：Python 项目门禁

目标：拦截未格式化 / 未过 lint 的 Python 代码。

repos:
  - repo: https://github.com/psf/black
    rev: 24.10.0
    hooks:
      - id: black          # 代码格式化
  - repo: https://github.com/pycqa/ruff
    rev: v0.8.4
    hooks:
      - id: ruff           # lint（含 --fix 自动修）
        args: [--fix]

效果：black 直接改写文件格式，改写过的文件本次提交被拦截，git add 后重新 commit 即过——门禁不是找茬，是替你改好再让你确认。

完整配置见交付包 demo/01-python/（含 .pre-commit-config.yaml + 故意写错的样例代码 + README 中文说明）。

四、场景 2：JavaScript / TypeScript 项目

repos:
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v9.0.0
    hooks:
      - id: eslint
        additional_dependencies:
          - typescript@5.6
          - eslint@9
  - repo: local
    hooks:
      - id: tsc
        name: tsc --noEmit
        entry: npx tsc --noEmit
        language: system
        files: \.tsx?$

要点：repo: local + language: system 组合可以直接调用项目内已有的命令行工具（tsc / vitest / go vet），不必等官方镜像仓库收录。

完整配置见 demo/02-javascript/。

五、场景 3：YAML / JSON / TOML 语法校验

业务痛点：CI 里「配置文件语法错误导致流水线挂半小时」是最冤的时间浪费。把它前移到 commit 时刻：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-yaml        # YAML 解析（含多文档支持）
        args: [--allow-multiple-documents]
      - id: check-json        # JSON 解析
      - id: check-toml        # TOML 解析
      - id: check-merge-conflict   # 拦截未解决完冲突标记的文件

典型拦截输出（中文对照）：

Check Yaml...............................................Failed
- hook id: check-yaml
- exit code: 1
   could not find expected ':' in "config/deploy.yaml" at line 12
   # ↑ 第 12 行缺冒号——去改，改完 git add 再 commit

完整配置 + 三个错误样例见 demo/03-yaml/。

六、场景 4：私钥与敏感信息防泄漏

业务痛点：.env / 私钥 / AK-SK 一旦 push 到远端，撤回 + 轮换的成本极高。pre-commit 可以在本地就拦住：

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks          # 800+ 种密钥模式识别
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: detect-private-key    # RSA / OPENSSH 私钥头识别
      - id: check-added-large-files
        args: [--maxkb=1024]      # 拦截 >1MB 的大文件（防误传二进制）

注意：gitleaks 扫的是暂存区新增内容，历史里已经泄漏的密钥要用 gitleaks detect --no-git 全量扫描确认，并立即轮换。

完整配置 + 模拟泄漏样例见 demo/04-secrets/。

七、场景 5：提交前跑自动化测试

目标：快失败的单元测试在 commit 时刻就拦截（全量测试留给 CI）。

repos:
  - repo: local
    hooks:
      - id: pytest-fast
        name: pytest (fast subset)
        entry: python3 -m pytest tests/unit -x -q --timeout=60
        language: system
        pass_filenames: false    # 不把文件名传给 pytest，固定跑目录
        stages: [pre-commit]

关键参数：

pass_filenames: false——pytest 按目录跑固定子集，不因 commit 文件变化而漂移；
-x 首个失败即停，控制门禁耗时在 1 分钟内；
耗时长的集成 / e2e 测试放 stages: [pre-push]（push 时才跑）。

完整配置见 demo/05-testing/。

八、常见坑速查

症状	原因	解法
hook 首次运行卡在 clone	网络问题	设置代理或镜像；缓存后不再下载
`pre-commit: command not found`	pip 用户目录不在 PATH	`python3 -m pre_commit` 直接调用
改了 config 不生效	hook 环境已缓存	`pre-commit clean` 或改 rev 后自动重建
想跳过一次检查	—	`git commit --no-verify`（ emergencies only，别养成习惯）

更多错误码（安装 / 自动修复 / 语法拦截 / 安全与大文件四大类）见配套文章《pre-commit 配置踩坑：错误码与解决方案》。

九、延伸阅读

pre-commit 官方文档
pre-commit GitHub 仓库
hook 集合市场
配套踩坑文：《pre-commit 配置踩坑：错误码与解决方案》

资源与声明

原项目：pre-commit/pre-commit
原项目许可证：MIT License（本店交付包内 LICENSES/ORIGINAL_LICENSE 附完整原文）
关于本店：本店提供「中文本地化增强包 / 打包整理服务」——包含上述 5 个场景完整可运行配置（demo/01-python ~ 05-testing）、中文错误码库（errors-zh/ 四大类 + INDEX）、中文快速上手文档（docs-zh/）。增强包为本店原创整理工作，与原项目官方无关联；原项目本身可从其官方渠道免费获取。
本店增强包内容基于原项目 commit a9bba55 整理，转载请注明原项目出处。

本文由裕普智汇 AI 智能体工厂整理发布。转载请注明出处。