Python 项目工程化:pyproject.toml、依赖锁定与可复现构建

目标:让本地与 CI 一致

工程化不是“工具越多越好”,而是把项目变成:

  • 新同学拉下来能跑
  • 你换电脑/换环境也能跑
  • CI 能稳定跑,并且失败好定位

一套推荐的落地顺序

  1. 统一入口:pyproject.toml
  2. 固定解释器版本(例如 3.11/3.12)
  3. 锁依赖(避免“今天装到 A,明天装到 B”)
  4. 加质量门禁:lint、测试、类型检查(按需)

pyproject.toml 里建议集中哪些配置

  • 格式化与 lint:ruff/black
  • 测试:pytest(覆盖率可选)
  • 类型检查:mypy(可选)

这样避免多个配置文件互相打架。

依赖管理的实用原则

  • 生产依赖与开发依赖分组
  • 升级小步快跑:一次升级一类核心依赖
  • 关键库要有版本约束区间,减少破坏性更新

目录结构建议(最小可维护)

1
2
3
4
5
project/
pyproject.toml
src/<pkg>/
tests/
.github/workflows/

CI 里的三个关键固定项

  1. Python 版本固定
  2. 依赖安装方式固定(用 lock 或者固定版本)
  3. 测试命令固定(不要“本地一个命令,CI 另一个命令”)

一条很管用的经验

当 CI 失败时,你应该能用“一条命令”在本地复现失败。否则工程化还没完成。