用 pre-commit 给 Python 项目加一道提交前的自动检查

举报
yd_16504198 发表于 2026/11/12 20:25:02 2026/11/12
【摘要】 最近在一个多人协作的小型 Python 项目里,代码评审时总有一半的评论在说格式问题:缩进不统一、import 顺序乱、行尾多余空格、偶尔还有调试用的 print 混进主分支。这类问题不难,但很耗评审者的耐心。后来我们给仓库加上了 pre-commit,让这些检查在每次 git commit 时自动完成,评审终于可以把注意力放回逻辑本身。下面记录一下配置过程和踩过的坑。一、pre-commi...

最近在一个多人协作的小型 Python 项目里,代码评审时总有一半的评论在说格式问题:缩进不统一、import 顺序乱、行尾多余空格、偶尔还有调试用的 print 混进主分支。这类问题不难,但很耗评审者的耐心。后来我们给仓库加上了 pre-commit,让这些检查在每次 git commit 时自动完成,评审终于可以把注意力放回逻辑本身。下面记录一下配置过程和踩过的坑。

一、pre-commit 是什么
pre-commit 是一个管理 Git 钩子的框架。它读取仓库根目录下的 .pre-commit-config.yaml,在提交前按顺序运行配置好的检查工具。每个工具都运行在独立的虚拟环境里,团队成员不需要手动安装 black、ruff 这些依赖,版本也由配置文件统一锁定。

二、三步完成配置

  1. 安装:pip install pre-commit
  2. 在仓库根目录新建 .pre-commit-config.yaml,配置 pre-commit-hooks(trailing-whitespace、end-of-file-fixer、check-yaml、check-added-large-files)和 ruff-pre-commit(ruff --fix、ruff-format)两个仓库,并用 rev 锁定版本。
  3. 安装钩子:pre-commit install
    之后每次 git commit,pre-commit 只会检查本次暂存的文件。如果工具自动修改了文件,提交会被中止,重新 git add 后再提交即可。

三、第一次全量检查
新接入的老仓库建议先跑一次 pre-commit run --all-files。我们第一次运行修改了四十多个文件,主要是行尾空格和 import 排序。建议把这次全量格式化单独作为一个提交,提交信息写清楚“仅格式化,无逻辑变更”,并把哈希写进 .git-blame-ignore-revs,方便以后 git blame 时跳过它。

四、踩过的几个坑

  1. 首次运行很慢:pre-commit 需要下载并创建各工具的环境,第一次可能要一两分钟,之后会使用缓存。网络不稳定时可以配置 pip 镜像源。
  2. 版本过旧:rev 字段写死了版本,时间久了工具会落后。定期执行 pre-commit autoupdate 即可升级,升级后最好再全量跑一次。
  3. 有人绕过检查:git commit --no-verify 可以跳过钩子。所以只靠本地钩子不够,我们在 CI 里也加了一步 pre-commit run --all-files,保证主分支始终干净。
  4. 大文件误提交:check-added-large-files 默认阈值是 500KB,曾经帮我们拦下了一个误放进仓库的测试数据集。确实需要较大文件时,可以通过 args 调整阈值,或者改用 Git LFS。

五、效果
接入一个月后,评审意见里关于格式的评论几乎消失,新成员也不需要先读一遍代码规范文档才能提交代码。整个配置文件不到二十行,投入很小,收益却很明显。如果你的团队也经常在评审里讨论空格和换行,不妨试试 pre-commit。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。