本文讲解为何需在 ci 中复用 pre-commit 钩子逻辑、如何通过可复用脚本实现零重复配置，并确保本地与 ci 使用完全一致的 linter 版本（如 ruff），兼顾开发效率与代码质量保障。
本文讲解为何需在 ci 中复用 pre-commit 钩子逻辑、如何通过可复用脚本实现零重复配置，并确保本地与 ci 使用完全一致的 linter 版本（如 ruff），兼顾开发效率与代码质量保障。
在现代 Python 工程实践中，pre-commit 是保障代码风格与质量的第一道防线，而 CI（如 GitHub Actions、Travis CI）则是最终的质量守门人。二者并非互斥，而是互补：pre-commit 提供即时、低延迟的本地反馈；CI 则提供不可绕过的强制校验——即使开发者使用 git commit --no-verify 或未正确安装钩子，CI 仍能兜底拦截问题代码。
✅ 推荐架构：统一入口，双向复用
核心原则是：将所有检查逻辑封装为独立、可调用的脚本（而非仅依赖 pre-commit 的 hook 配置）。这样既能被 pre-commit 调用，也能被 CI 直接执行，天然保证行为与版本一致性。
以主流工具 Ruff 为例，推荐结构如下：
# project-root/ ├── scripts/ │ └── lint.sh # 统一入口：调用 ruff check + ruff format --check ├── .pre-commit-config.yaml ├── pyproject.toml # 声明 ruff 版本（如 ruff = ">=0.5.0,<0.6.0"） └── .github/workflows/ci.yml # 或 .travis.yml
scripts/lint.sh 示例（POSIX 兼容）：
#!/usr/bin/env bash set -e # 确保使用 poetry 环境中的 ruff（版本由 pyproject.toml 锁定） poetry run ruff check --output-format=github . poetry run ruff format --check --diff .
✅ 关键优势：
- 版本由 pyproject.toml 统一声明，poetry install 后 poetry run ruff 自动匹配；
- CI 和 pre-commit 均调用同一脚本，杜绝“本地通过但 CI 失败”的版本漂移问题；
- 开发者可随时手动运行 ./scripts/lint.sh 快速验证。
? pre-commit 配置（调用脚本）
# .pre-commit-config.yaml
- repo: local
hooks:
- id: lint
name: Run unified lint script
entry: ./scripts/lint.sh
language: script
types: [python]? CI 配置（复用同一脚本）
# .github/workflows/ci.yml
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: snok/install-poetry@v1
- run: poetry install
- run: ./scripts/lint.sh # ← 完全复用！⚠️ 注意事项与最佳实践
- 禁止在 CI 中直接复制 pre-commit run：pre-commit 在 CI 中需额外安装钩子（pre-commit install），且其环境隔离可能引入版本偏差；
- 避免硬编码工具版本：始终通过 pyproject.toml 的 [tool.ruff] 或 poetry.lock 控制版本，脚本仅负责调用；
- CI 中启用 --fix 需谨慎：建议 CI 仅做 --check（只报错不修复），修复动作保留在本地或 PR 机器人中；
- 扩展性设计：后续新增检查（如 mypy、codespell）只需扩展 lint.sh，无需修改 CI 或 pre-commit 配置。
? 总结
同步 pre-commit 与 CI 并非过度工程，而是稳健协作的基石。通过「脚本化检查逻辑 + 统一依赖声明」的模式，你既能享受本地即时反馈的开发体验，又能确保 CI 成为不可逾越的质量闸门——所有规则、所有版本，一处定义，处处生效。
