requirements.txt 是项目依赖的“契约文件”，需区分生产与开发依赖；推荐分层管理：base.txt 为运行时依赖并锁定版本，dev.txt 为开发工具，避免线上环境冗余安装。
Python 的 requirements.txt 不是简单地把当前环境所有包 dump 出来就完事，它本质是项目依赖的“契约文件”——既要保证可复现，又要兼顾可维护性和安全性。
明确区分生产依赖与开发依赖
把所有包（比如 pytest、black、mypy）都塞进主 requirements.txt 会导致线上环境安装无用工具，增加攻击面和部署体积。推荐采用分层方式：
-
requirements/base.txt：核心运行时依赖（如 Django、requests、psycopg2-binary），版本锁定到小版本（Django==4.2.11）或兼容性范围（requests>=2.28.0,） -
requirements/dev.txt：继承 base，并追加开发/测试工具，用-r base.txt引入，避免重复和冲突 - CI/CD 和生产环境只安装
base.txt；本地开发用pip install -r requirements/dev.txt
避免使用 pip freeze > requirements.txt
直接 freeze 会导出整个虚拟环境的包（含依赖的依赖、可选依赖、甚至 pip/setuptools 自身），导致：
- 版本过度约束（如
asgiref==3.7.2被硬锁，但 Django 4.2 只要求>=3.7.2，后续小版本修复无法自动获取） - 引入间接依赖（如
pyyaml是django-environ的子依赖），主项目未声明却强绑定，易引发升级断裂 - 包含平台相关包（如
pkg-resources）或本地路径包（-e ./mylib），无法跨环境安装
正确做法：手动编写 base.txt，只写你**直接 import 并明确依赖**的包；用 pip-tools 或 pip-compile 自动生成锁定文件（如 requirements.lock）供部署使用。
立即学习“Python免费学习笔记（深入）”；
谨慎处理版本号策略
版本写法直接影响可维护性与稳定性：
- ✅ 推荐：
requests>=2.28.0, —— 允许安全补丁和小版本更新，符合语义化版本规范 - ⚠️ 慎用：
Flask==2.3.3—— 仅在有明确兼容性问题时锁定，否则阻碍自动安全更新 - ❌ 避免：
numpy（无版本）—— 安装最新版，极大概率导致环境不一致或构建失败 - 特别注意：C 扩展包（如
psycopg2-binary、pydantic）建议锁定小版本，因大版本常含 breaking change
补充必要元信息与自动化保障
让 requirements 更易读、可审计、防误操作：
- 每行末尾添加简短注释说明用途（
# for async HTTP calls），尤其对非显性依赖（如aiosignal） - 在项目根目录放
.pip-tools.cfg统一配置编译行为（如--upgrade-strategy=eager） - CI 中加入检查步骤：运行
pip-compile --dry-run确保 lock 文件与 .in 同步；用safety check -r requirements.lock扫描已知漏洞 - Git 提交前运行
pip-compile更新 lock 文件，确保每次提交都是确定状态
本质上，requirements.txt 是团队协作的接口协议——写得越精确，环境越稳定；管得越松散，排查越头疼。不复杂但容易忽略。
