Python 项目工程化:pyproject.toml、依赖锁定与可复现构建
Python 项目工程化:pyproject.toml、依赖锁定与可复现构建
目标:让本地与 CI 一致
工程化不是“工具越多越好”,而是把项目变成:
- 新同学拉下来能跑
- 你换电脑/换环境也能跑
- CI 能稳定跑,并且失败好定位
一套推荐的落地顺序
- 统一入口:
pyproject.toml - 固定解释器版本(例如 3.11/3.12)
- 锁依赖(避免“今天装到 A,明天装到 B”)
- 加质量门禁:lint、测试、类型检查(按需)
pyproject.toml 里建议集中哪些配置
- 格式化与 lint:
ruff/black - 测试:
pytest(覆盖率可选) - 类型检查:
mypy(可选)
这样避免多个配置文件互相打架。
依赖管理的实用原则
- 生产依赖与开发依赖分组
- 升级小步快跑:一次升级一类核心依赖
- 关键库要有版本约束区间,减少破坏性更新
目录结构建议(最小可维护)
1 | project/ |
CI 里的三个关键固定项
- Python 版本固定
- 依赖安装方式固定(用 lock 或者固定版本)
- 测试命令固定(不要“本地一个命令,CI 另一个命令”)
一条很管用的经验
当 CI 失败时,你应该能用“一条命令”在本地复现失败。否则工程化还没完成。
本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 咻咻咻小陈的空间!