Python pre-commit.ci 的加速技巧

根本原因是pre-commit.ci默认为每个hook启动全新docker容器且不复用pip缓存，导致大包安装耗时30–90秒；需禁用autoupdate、显式配置cache路径、优化hook配置并合理使用stages。

pre-commit.ci 为什么比本地 pre-commit 慢

根本原因不是网络，而是它默认为每个 hook 启动全新 Docker 容器，且不复用缓存层。本地 pre-commit run 走的是已安装的 python 环境 + pip 缓存，而 pre-commit.ci 的每次运行都从基础镜像拉起，pip install 阶段占时最长。

• hook 若依赖大包（如 pylint、black 24+、mypy），安装耗时可达 30–90 秒
• 即使用了 language: system，pre-commit.ci 仍可能 fallback 到容器环境，不保证复用宿主 Python
• 默认配置下，ci: autoupdate: true 会触发额外的 pre-commit autoupdate 步骤，进一步拖慢

用 pre-commit.ci 的 cache 声明跳过重复安装

pre-commit.ci 支持在 .pre-commit-config.yaml 里显式声明缓存路径，让 pip 安装结果跨构建复用。关键是把 ~/.cache/pip 和 hook 的 virtualenv 目录都加进缓存键。

• 在 .pre-commit-config.yaml 顶层加：

  ci:   skip: []   autoupdate: false   # 关键：启用缓存并指定路径   cache:     - ~/.cache/pip     - .pre-commit-hooks

• 必须关掉 autoupdate，否则每次 PR 都会先跑一次更新，清空旧缓存
• 如果 hook 使用 language: python，其虚拟环境默认建在 .pre-commit-hooks/ 下，缓存该目录能直接跳过 reinstall
• 注意：缓存只对同一 repo 的后续构建生效，fork 的 PR 不共享缓存

替换 heavy hook 为轻量等效命令

有些 hook 天然重，比如 mypy 全项目检查或 pylint 启用全部插件。pre-commit.ci 上没必要全量跑，可换为只检改动文件的轻量替代。

• 把 repo: https://github.com/pre-commit/mirrors-mypy 换成自定义脚本：

  - repo: local   hooks:     - id: mypy-changed       name: mypy (changed files only)       entry: sh -c 'mypy --show-error-codes $(git diff --cached --name-only | grep ".py$" | tr "n" " ")'       language: system       types: [python]

• 避免用 black 24+，改用 black==23.10.1 —— 新版因 AST 重构导致启动慢 2–3 倍
• pylint 建议加 args: [--disable=all,--enable=missing-docstring,unused-argument]，禁用开销大的检查项

用 pre-commit.ci 的 stages 控制执行时机

默认所有 hook 在 push 和 pull_request 都跑，但有些只需在合并前校验（比如严格格式检查），有些甚至可以只在 push 到 main 时跑（比如生成 changelog）。

立即学习“Python免费学习笔记（深入）”；

• 给 hook 加 stages: [commit] 只在本地 commit 触发，CI 不执行
• 对耗时 hook（如 codespell 全量扫描），设 stages: [push]，避开 PR 检查的等待
• 若 hook 依赖 CI 特有 secret（如上传报告），用 pass_filenames: false + always_run: true 避免因无改动文件被跳过
• 注意：stage 设置只影响 pre-commit.ci 的触发逻辑，不影响本地行为

真正卡住速度的，往往不是单个 hook 多慢，而是多个 hook 的 pip 安装叠加 + 默认全量扫描 + 未关闭 autoupdate。缓存路径写错、stage 混用、或以为加了 language: system 就一定快——这些才是实际落地时最常漏掉的点。