基于pre-commit的Python代码规范落地实践

郑文峰的博客

使用dify对接飞书多维表格使用n8n对接飞书多维表格服务启动时出现 OOM 一次服务升级时pg表DDL执行超时失败 Go语言高效IO缓冲技术详解 Go语言延迟初始化(Lazy Initialization)最佳实践 Go语言字符串拼接性能对比与优化指南 Go语言结构体内存对齐完全指南 Go语言空结构体：零内存消耗的高效编程 Go语言堆栈分配与逃逸分析深度解析 Go语言原子操作完全指南 Go语言内存预分配完全指南 Go语言不可变数据共享：无锁并发编程实践 Go语言零拷贝技术完全指南 Go语言遍历性能深度解析：从原理到优化实践 Go语言Interface Boxing原理与性能优化指南 Go协程池深度解析：原理、实现与最佳实践使用etcd分布式锁导致的协程泄露与死锁问题初识 MCP Server pulsar阻塞导致logstash无法接入日志 django-prometheus使用及源码分析 kube-proxy源码分析 kubernetes service如何通过iptables转发 tcp缓存引起的日志丢失 django-apschedule定时任务异常停止理解calico容器网络通信方案原理理解flannel的三种容器网络方案原理理解Linux IPIP隧道理解VXLAN网络理解Linux TunTap设备

zhengwenfeng · 2025-05-12 · via 郑文峰的博客

# 简介

pre-commit 是一个开源工具，用于管理和执行 Git 钩子，确保代码库的一致性和质量。通过在提交代码前自动运行代码风格检查（Linting）和格式修正（Formatting），它有助于保持项目代码的统一标准。本文将通过一个 Python 项目的实例，展示如何配置 pre-commit 工作流。

本文旨在介绍使用 pre-commit 对 Python 项目进行代码检查的方法，以提前发现并解决代码中的问题，提高代码的整体质量。文中提及的所有代码示例可以在 pre-commit-demo (opens new window) 找到。

# 使用

安装

首先，安装 pre-commit：

安装成功后，您可以通过以下命令验证安装是否成功：

$ pre-commit --version 
pre-commit 4.2.0

1
2

接下来，设置 Git 钩子脚本：

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

1
2

创建配置文件在项目的根目录下创建 .pre-commit-config.yaml 文件，并推荐使用最新稳定版：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: check-yaml
      - id: check-json
      - id: check-toml
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/isort
    rev: 5.13.2
    hooks:
      - id: isort
  - repo: https://github.com/PyCQA/flake8
    rev: 7.2.0
    hooks:
      - id: flake8

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

配置文件说明:

repos: 包含要使用的仓库列表。
repo: 每个仓库的 URL。
rev: 版本号，建议使用最新稳定版。
hooks: 需要执行的钩子列表。
id: 各个钩子的标识符。

每个钩子 ID 的具体作用可参考相应仓库的官方文档。

执行与应用

在执行 commit 命令时，会自动调用配置文件中定义的钩子脚本，检查代码是否符合规范。例如：

$ pre-commit_demo % git add *
$ pre-commit_demo % git commit -m "add main.py"
Check Yaml...........................................(no files to check)Skipped
Check JSON...........................................(no files to check)Skipped
Check Toml...........................................(no files to check)Skipped
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
[main 27890fe] add main.py
 1 file changed, 1 insertion(+)
 create mode 100644 main.py

1
2
3
4
5
6
7
8
9
10
11
12
13

默认情况下，仅检查新添加或修改的文件。若需手动检查所有文件，可以使用如下命令：

$ pre-commit run --all-files
Check Yaml...............................................................Passed
Check JSON...........................................(no files to check)Skipped
Check Toml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed

1
2
3
4
5
6
7
8
9

如需临时跳过校验，可在 commit 命令中加上 --no-verify 参数：

$ git commit -m "add main.py" --no-verify

# 最佳实践

将.pre-commit-config.yaml纳入版本控制，确保团队配置一致
定期运行pre-commit autoupdate保持工具最新版本
优先修复而不是--no-verify，让规范成为肌肉记忆.

# 总结

通过本文的实践，我们已经为Python项目搭建了自动化代码质检流水线。pre-commit 就像一位尽职的代码审查员，帮我们做到：

规范守护者：自动执行代码格式化（Black/isort）和静态检查（flake8）
效率加速器：拦截问题在提交前，避免CI/CD环节反复返工
团队协作者：统一项目代码风格，降低多人协作成本

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

郑文峰的博客

# 简介

# 使用

# 最佳实践

# 总结