Python仓库Pre-commit钩子Docker镜像

镜像概述

本镜像专为Python项目设计，提供开箱即用的pre-commit钩子环境，集成多种Python代码质量工具，支持在代码提交前自动化执行格式化、静态检查、类型验证等操作，无需在本地配置复杂依赖，简化开发流程并确保代码规范统一。

核心功能与特性

• 多工具集成：包含代码格式化（black、isort）、静态检查（flake8、pylint）、类型检查（mypy）、安全扫描（bandit）等常用工具
• 环境隔离：通过Docker容器化运行，避免本地Python环境冲突，确保团队使用一致的检查标准
• 灵活配置：支持通过.pre-commit-config.yaml自定义钩子类型、工具版本及参数
• 轻量高效：基于Python官方镜像构建，体积优化，首次运行后缓存依赖以提升后续执行速度

使用场景

• Python项目开发：个人或团队开发中，在提交代码前自动执行质量检查，拦截不规范代码
• 团队协作：统一代码风格和质量标准，减少代码评审中的格式类问题
• CI/CD前置验证：作为CI流程的预检查步骤，在构建前过滤不合格代码
• 开源项目维护：确保贡献者提交的PR符合项目代码规范

使用方法

基本使用流程

1. 准备项目环境：确保项目根目录包含.pre-commit-config.yaml配置文件（无配置时使用默认规则）
2. 运行镜像检查：通过Docker命令挂载项目目录并执行检查

基础命令示例

# 检查所有文件（首次运行会下载依赖，需联网）
docker run --rm -v $(pwd):/app -w /app [镜像名称] pre-commit run --all-files

# 检查暂存文件（模拟git commit触发的钩子行为）
docker run --rm -v $(pwd):/app -w /app [镜像名称] pre-commit run

自定义钩子配置

通过项目根目录的.pre-commit-config.yaml文件定义检查规则，示例配置：

repos:
  - repo: [***]
    rev: 24.4.2  # 指定black版本
    hooks:
      - id: black
        args: [--line-length=120]  # 自定义行长度

  - repo: [***]
    rev: 7.0.0
    hooks:
      - id: flake8
        args: [--max-line-length=120, --ignore=E203]  # 忽略特定规则

  - repo: [***]
    rev: 1.8.0
    hooks:
      - id: mypy
        args: [--strict, --config-file=mypy.ini]  # 使用自定义配置文件

集成Git工作流

1. 创建便捷脚本（run-pre-commit.sh）：

   #!/bin/bash
   docker run --rm -v $(pwd):/app -w /app [镜像名称] pre-commit run "$@"
   

2. 赋予执行权限：chmod +x run-pre-commit.sh
3. 配置为Git提交钩子：

   # 链接脚本到Git钩子目录
   ln -s ../../run-pre-commit.sh .git/hooks/pre-commit
   

   此后执行git commit时将自动触发检查，若检查失败则阻止提交

配置参数

环境变量

• PRE_COMMIT_CONFIG：自定义配置文件路径，默认值为/app/.pre-commit-config.yaml
  示例：docker run -e PRE_COMMIT_CONFIG=/app/configs/pre-commit.yaml ...

挂载需求

• 项目目录：必须挂载到容器内/app目录（或通过-w指定其他工作目录）
• 配置文件：需将项目中的.flake8、pyproject.toml、mypy.ini等配置文件挂载到容器内对应路径，确保工具读取自定义规则

注意事项

• 首次运行会下载钩子工具和依赖，建议在网络良好环境下执行
• 对于依赖项目特定库的检查（如mypy类型检查），需确保容器内已安装项目依赖，可通过挂载requirements.txt并在容器内执行pip install -r requirements.txt实现
• 敏感文件（如密钥）建议通过.gitignore排除，避免挂载到容器内