modern-python 工具链中的 prek 实战指南：Rust 原生的快速 Pre-commit 钩子管理器

AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载prek 是一个用 Rust 编写的 pre-commit 快速替代品完全兼容现有的.pre-commit-config.yaml配置格式是当前仓库modern-python插件位于 plugins/modern-python推荐的 Git 钩子管理方案。读完本文你将掌握 prek 的安装、命令用法、安全钩子配置、CI 集成与从 pre-commit 的迁移步骤并能基于本仓库的完整配置模板与源码证据搭建一套更快速、更安全的提交前检查流水线。prek 是什么与 pre-commit 的定位差异prek 是一个快速、Rust 原生的 pre-commit 直接替代品drop-in replacement。它沿用 pre-commit 的.pre-commit-config.yaml格式与现有配置完全兼容因此从 pre-commit 切换的成本极低。在本仓库的 SKILL.md 中prek 被列为现代 Python 工具链的标准组成部分Tool Overview 表中prek | Pre-commit hooks | pre-commit (faster, Rust-native)并在反模式对照表中明确建议以prek替代pre-commit理由为更快、无需 Python 运行时。特性对比prek vs pre-commit特性prekpre-commit速度钩子安装约快 7 倍较慢依赖单一二进制无需运行时需要 Python磁盘占用钩子之间共享工具链隔离环境并行性并行克隆仓库与并行执行钩子顺序执行Python 管理自动使用 uv手动配置 PythonMonorepo 支持内置 workspace 模式不支持其中约快 7 倍的钩子安装速度内置 workspace 模式共享工具链等描述来自 prek 官方项目文档作为选型依据参考即可实际收益建议在目标仓库中自行基准验证。已经在使用 prek 的项目据 prek 项目官方页面的采用者清单包括 CPython、Apache Airflow、FastAPI、Ruff、Home Assistant 等知名项目。安装 prek本仓库的 security-setup.md 提供了三种主要安装方式另有uv tool install可用于工具化安装# Homebrew推荐macOS/Linux brew install prek # Cargo cargo install prek # 独立安装脚本 curl --proto https --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh # 通过 uv 工具化安装与 modern-python 工具链风格一致 uv tool install prek选择依据brew install prek适合日常开发机cargo install prek适合 Rust 工具链已就绪的环境独立安装脚本适合 CI 与无包管理器的环境uv tool install prek则与本插件一切工具走 uv的理念一致也出现在本文后续的 CI 配置中。快速上手面向现有 pre-commit 用户直接换命令prek 与.pre-commit-config.yaml完全兼容只需要替换命令即可# 原命令: pre-commit install prek install # 原命令: pre-commit run --all-files prek run --all-files # 原命令: pre-commit autoupdate prek auto-update全新项目配置创建.pre-commit-config.yamlrepos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: latest # 具体版本请查阅该仓库 releases 页 hooks: - id: ruff args: [--fix] - id: ruff-format安装并运行# 安装 git hooks注册到 .git/hooks提交前自动执行 prek install # 手动对所有文件运行 prek run --all-files # 运行指定钩子 prek run ruff配置文件详解对于开箱即用的完整配置可以直接复制本仓库的 templates/pre-commit-config.yaml 到仓库根目录。该模板已按代码质量 / 通用文件检查 / 安全钩子三块组织并包含逐钩子的注释说明。推荐配置default_language_version与安全钩子注意以下配置中的latest是占位符。使用前务必打开对应 releases 页面确认当前稳定版本并替换为具体版本号。# See https://pre-commit.com for more information default_language_version: python: python3.12 repos: # Ruff - linting and formatting - repo: https://github.com/astral-sh/ruff-pre-commit rev: latest # https://github.com/astral-sh/ruff-pre-commit/releases hooks: - id: ruff args: [--fix] - id: ruff-format # General file checks (prek builtin - faster, no external deps) - repo: builtin hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-merge-conflict # Security hooks - see security-setup.md for detailed guidance # Shell script linting - repo: https://github.com/koalaman/shellcheck-precommit rev: latest # https://github.com/koalaman/shellcheck-precommit/tags hooks: - id: shellcheck args: [--severityerror] # Secret detection - repo: https://github.com/Yelp/detect-secrets rev: latest # https://github.com/Yelp/detect-secrets/releases hooks: - id: detect-secrets args: [--baseline, .secrets.baseline] # GitHub Actions linting - repo: https://github.com/rhysd/actionlint rev: latest # https://github.com/rhysd/actionlint/releases hooks: - id: actionlint # GitHub Actions security audit - repo: https://github.com/zizmorcore/zizmor-pre-commit rev: latest # https://github.com/zizmorcore/zizmor-pre-commit/releases hooks: - id: zizmor args: [--personaregular, --min-severitymedium, --min-confidencemedium]各安全钩子逐一解析详细说明见 security-setup.mdshellcheck--severityerror捕捉 shell 脚本常见问题——未加引号的变量展开SC2086、未加引号的命令替换SC2046、掩盖返回值的声明与赋值混写SC2155。先从error级别开始必要时再放宽。detect-secrets--baseline, .secrets.baseline防止 API 密钥、密码、令牌被提交。首次使用必须先生成基线见下文初始化基线钩子失败时用detect-secrets audit --report .secrets.baseline查看命中误报则detect-secrets scan --update .secrets.baseline更新基线确为真实密钥则删除并轮换凭据。actionlint校验 workflow 语法错误、非法事件触发器、未定义的 workflow 输入、run:块中的 shell 语法错误以及无效的 action 版本引用也可手动运行actionlint .github/workflows/。zizmor--personaregular, --min-severitymedium, --min-confidencemedium审计 workflow 安全重点发现excessive-permissions缺permissions:块、template-injection不安全地使用${{ github.event.* }}、unpinned-actionaction 未固定 SHA、dangerous-triggerspull_request_target配合 checkout。默认 workflow 拥有全部write权限建议显式收窄例如只读工作流声明permissions: contents: read需要发版或评论 PR 时再按需放开。使用内置钩子builtin hooksprek 内置了常用钩子的 Rust 原生实现运行更快且不依赖外部环境同时支持离线使用repos: - repo: builtin hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-json - id: check-toml仓库模板在通用文件检查段选用了trailing-whitespace、end-of-file-fixer、check-yaml、check-toml、check-merge-conflict五个内置钩子这些检查几乎适用于任何仓库且零外部依赖。命令参考命令说明prek install安装 git hooksprek uninstall移除 git hooksprek run对暂存文件运行钩子prek run --all-files对所有文件运行prek run --last-commit对上一次提交涉及的文件运行prek run HOOK [HOOK...]运行指定钩子prek run -d src/对指定目录中的文件运行prek auto-update更新钩子版本prek list列出已配置的钩子prek clean清理缓存环境注意区分默认行为与显式范围prek run默认只检查暂存staged文件适合提交前快速验证prek run --all-files用于全量检查CI 场景-d支持按目录定向检查。CI 集成GitHub Actions推荐使用官方 actionname: Pre-commit on: [push, pull_request] jobs: prek: runs-on: ubuntu-latest steps: - uses: actions/checkoutsha # 具体 SHA 见 actions/checkout releases 页 - uses: j178/prek-actionsha # 具体 SHA 见 j178/prek-action releases 页GitHub Actions手动安装- name: Install prek run: uv tool install prek - name: Run hooks run: prek run --all-files推荐在 CI 中使用prek run --all-files确保全量文件被检查而非只检查变更文件。与钩子版本固定同理CI 中的 action 也应固定到具体 SHA本仓库 migration-checklist.md 的 CI 清理清单同样要求将 GitHub Actions 固定到 SHA。Makefile 集成.PHONY: hooks hooks-install hooks: prek run --all-files hooks-install: prek install将hooks目标接入日常开发流程如make hooks提交前全量检查与 SKILL.md 中推荐的 Makefile 工作流lint/format/test目标保持一致。从 pre-commit 迁移安装 prekuv tool install prek移除 pre-commitpip uninstall pre-commit或uv tool uninstall pre-commit重新安装 hooksprek install可选清理旧环境rm -rf ~/.cache/pre-commit迁移后你现有的.pre-commit-config.yaml无需任何修改即可继续工作——这正是drop-in replacement的核心价值。清理旧缓存可以释放 pre-commit 历史上隔离环境占用的磁盘空间。最佳实践清单CI 中使用prek run --all-files——确保全量文件被检查而非仅变更文件固定钩子版本——rev使用具体版本号而非分支保证可复现性auto-update使用--cooldown-days——缓解供应链攻击prek auto-update --cooldown-days 7优先使用内置钩子——repo: builtin的常见检查更快、可离线运行提交前运行钩子——prek install会自动完成注册首次提交前初始化 detect-secrets 基线——执行detect-secrets scan .secrets.baseline并审查后提交基线文件。其中第 3 条的7 天冷却期与本仓库的供应链安全思路一脉相承模板 dependabot.yml 同样为依赖更新配置了cooldown: default-days: 7防止攻击者发布恶意更新后在检测前被快速采纳。在本仓库中的定位与实现佐证prek 并非孤立工具它深度嵌入 modern-python 插件的整体设计工具链定位SKILL.md 的 Tool Overview 表将 prek 与 uv、ruff、ty、pytest 并列为核心工具安全工具表shellcheck、detect-secrets、actionlint、zizmor的运行时机均标注为 pre-commit即由 prek 驱动。完整模板templates/pre-commit-config.yaml 是本文推荐配置的直接来源文件头注释写明复制到仓库根目录后使用prek install与prek run --all-files。与 PATH shim 机制的兼容性插件通过 hooks/hooks.json 注册的 SessionStart 钩子安装python/pip/pipx/uv的 PATH shim拦截裸命令并提示 uv 替代写法。根据 README.md 与 hooks/shims/python 头部注释shim 特意放行了python -c、python -m module、python -以及带--project/--directory/--target的uv pip调用因为此前拦截这些调用破坏过真实工具链——其中就包括prek 的钩子安装流程对应 issue #207。这从侧面说明 prek 已是该插件生态中实际运转的一环配置 prek 时应避免用裸python解释器或非 uv 方式运行钩子脚本。供应链纵深security-setup.md 还覆盖了 CI 阶段的依赖漏洞扫描pip-audit与自动化更新Dependabot与 prek 的本地钩子形成提交前 CI 定时三层防线二者分工可概括为pip-audit 回答当前依赖是否已有已知漏洞Dependabot 防止长期落后积累漏洞。小结prek 以单二进制、Rust 原生、配置零改动的方式切入 pre-commit 生态在安装速度、并行度、磁盘占用和 monorepo 支持上提供了可感知的改进。结合本仓库的推荐配置模板、安全钩子矩阵与供应链冷却期策略你可以用最小的迁移成本把 Python 项目的提交前检查升级为更快、更安全、更适合 CI 的现代化流水线。配置迁移、钩子增删与日常执行都以.pre-commit-config.yaml为唯一事实来源团队协作时心智负担几乎为零。赞分享AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载相关推荐hcledit实战pre-commit-terraform_wrapper_module_for_each钩子代码生成原理hcledit实战pre commit terraform_wrapper_module_for_each钩子代码生成原理 在Terraform基础设施即代diagrams.netdraw.io桌面版快速安装教程3 步用免费离线绘图工具覆盖三平台diagrams.netdraw.io桌面版快速安装教程3 步用免费离线绘图工具覆盖三平台 diagrams.netdraw.io桌面版是一款免费开源桌面应用图形学Lemon Squeezy 自动化实战指南基于 Composio 与 Rube MCP 驱动商品、订单与订阅全流程管理Lemon Squeezy 自动化实战指南基于 Composio 与 Rube MCP 驱动商品、订单与订阅全流程管理 Lemon Squeezy 是面向数字AI 技能AI 插件人工智能工作流自动化上一篇抖音批量下载器完整指南3步实现高效无水印视频与封面提取下一篇ok-ww 鸣潮自动战斗自定义技能循环指南角色代码热加载机制的 4 层拆解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考