别再乱加==了!Python依赖版本管理最佳实践
- 2026-10-11 07:52:26
👇 关注公众号，并选择星标，最新干货每日送达
导读
你是不是也遇到过这种情况？本地写的代码跑的好好的，部署到服务器一运行就报错，查了半天最后发现是requests版本比本地低了0.0.1，某个API参数变了。更气人的是，你明明在requirements.txt里写了requests>=2.25.0，怎么就装上2.24.0了？这背后其实是你对版本约束符号的理解根本不对。
⬆️AI生成
基础规则详解
很多人写requirements.txt要么只会写包名，要么全加==锁死版本，其实pip遵循PEP 440规范，有7个明确的版本约束符号，先搞懂版本号规则：主版本号.次版本号.修订号，主版本升代表不兼容API变更，次版本升加新功能，修订号升只修bug。
**==**：精确匹配某一版本，如 requests==2.25.1，只能装这个版本，大部分场景属于滥用**>= / <=**：大于等于/小于等于指定版本，最常用组合 >=2.25.0,<3.0.0**> / <**：大于/小于指定版本，不包含等于 **!=**：排除某个有bug的版本，如 requests!=2.25.0~=：兼容更新，最推荐用的符号， ~=2.25.0=≥2.25.0且<2.26.0，~=2.25=≥2.25.0且<3.0.0，既能收bug修复，又不会升到不兼容版本
版本约束的核心不是限制，而是用明确的规则减少不确定性。
⬆️AI生成
我见过最离谱的是有人在requirements.txt里写requests==2.25.0，然后另一个依赖包要求requests>=2.26.0，pip直接冲突报错，他还以为是pip坏了。
进阶使用技巧
组合约束规则
多个约束取交集，如requests>=2.25.0,<3.0.0,!=2.25.2，代表2.25.0到3.0.0之间，排除2.25.2版本。注意两点：
不要写矛盾约束如 >=2.26.0,<2.25.0，pip直接报错默认不安装预发布版本（alpha/rc版），除非约束里明确写 >=2.26.0rc1
特殊场景写法
Git依赖： package @ git+https://github.com/user/repo.git@commit#egg=package，直接锁死代码版本，开发临时用，上线一定要转正式发布版环境标记：跨平台项目用，如 pywin32>=300; sys_platform == 'win32'，只有Windows系统才需要安装
最佳实践清单
库松应用严：开发Python库给别人用，用宽松约束 >=x.y.z,<x+1.0.0；做业务应用，用lock文件锁死所有依赖的精确版本必加大版本上限：所有依赖都加 <x+1.0.0，避免包发大版本API变更直接炸项目，我至少踩过三次这个坑不要直接用pip freeze生成依赖：会导出整个环境的无关包，推荐用pip-compile或poetry管理 定期升级依赖：一两个月抽时间升一次，不要等出了安全漏洞再临时抱佛脚
好的requirements.txt不是越严格越好，而是在稳定性和灵活性之间找到平衡点。
我们团队现在用的是Pipenv，虽然有一些小毛病，但虚拟环境和依赖管理集成在一起，对于新人来说更友好，不容易搞混环境。
自动生成工具指南
自动生成不是银弹，不同工具的优缺点差很多，按需选：
⬆️AI生成
1. pip freeze（最不推荐）
用法： pip freeze > requirements.txt问题：会导出整个环境的所有包（包括临时测试的、系统自带的），全是==锁死，别人拿到根本装不上，平台不兼容 仅适合：导出当前环境快照排查问题，不要作为项目依赖声明
2. pipreqs（小脚本临时用）
用法： pipreqs /path/to/project --encoding=utf8，扫描代码自动提取import的依赖问题：漏识别动态import、版本匹配不准，适合简单的单文件脚本，不要用在项目上
3. pip-compile（中型项目推荐）
用法：先手写requirements.in放直接依赖（如 requests>=2.25.0,<3.0.0），运行pip-compile requirements.in自动生成带精确版本的requirements.txt问题：解析速度慢，冲突报错反人类，胜在轻量，不需要改现有项目结构
4. poetry/pipenv（中大型项目推荐）
用法：在pyproject.toml里加依赖，自动生成lock文件锁死所有版本，要导出requirements用 poetry export问题：学习成本高，lock文件复杂，胜在依赖管理清晰，适合团队协作
自动生成工具通用问题
不会自动加大版本上限、不会判断跨版本兼容性、平台相关依赖处理不好，生成之后一定要手动检查一遍，删掉不需要的依赖，补全版本上限。
安装使用指南
基础安装： pip install -r requirements.txt常用参数：加 -i 国内源地址提速，--no-cache-dir避免缓存问题升级依赖：加 -U参数升级到约束内最新版本重点提醒：一定要用虚拟环境，不要往系统Python里装依赖，不然不同项目版本冲突能把你搞疯 问题解决：冲突看报错信息调约束，权限不够加--user，慢就换国内源
常见避坑指南
**别滥用==**：锁死版本会导致收不到安全更新，应用项目用lock文件锁版本，不要直接在requirements.txt里全写== 搞懂~=的范围： ~=2.25和~=2.25.0差很多，前者允许升到2.99.0，后者只能在2.25.x范围内，别写错导致不兼容注意依赖传递：你写的直接依赖约束会覆盖传递依赖的约束，遇到冲突要仔细排查 区分开发/生产依赖：pytest、flake8这类开发工具不要写到生产依赖里，分开存到requirements-dev.txt
刚学Python的时候不知道虚拟环境，所有项目都往系统Python里装，最后版本冲突到连pip都用不了，只能重装Python，搞了一下午。
参考资料
PEP 440 版本标识规范： https://peps.python.org/pep-0440/ pip 版本约束符号官方文档： https://pip.pypa.io/en/stable/reference/requirement-specifiers/ 兼容版本约束官方说明： https://peps.python.org/pep-0440/#compatible-release Python官方依赖管理指南： https://packaging.python.org/en/latest/guides/dependency-management/ pip 依赖解析规则： https://pip.pypa.io/en/stable/topics/dependency-resolution/ 预发布版本匹配规则： https://peps.python.org/pep-0440/#pre-releases Stack Overflow相关讨论： https://stackoverflow.com/questions/39577982/what-is-the-difference-between-and-in-requirements-txt
公众号后台回复「加群」加入互助群。
文章仅做学术分享，如有侵权请联系删除，非常感谢！
