根本原因是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、black24+、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 上没必要全量跑，可换为只检改动文件的轻量替代。
doxygen是一款好用的程序员辅助工具，它可以让程序添加批添代码更加简单轻松，兼容C++、 C、Java、 Objective-C、Python等主流编程语言，小编提供的doxygen中文手册包含了基本介绍、语法技巧以及进阶技巧等内容，可以让你快速上手操作，有需要的欢迎下载。 基本介绍 Doxygen已经支持生成ANSI编码的chm目录文件(index.hhc)!Doxygen通常是用作生成英文文档的，生成中文文档需要修改输入和输出的码制，这样可以改变解析方式，生成中文文档。但是，你必须意识 到，Dox
- 把
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] - 避免用
black24+，改用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 就一定快——这些才是实际落地时最常漏掉的点。
