1. 为什么需要自动生成requirements.txt
在Python项目开发中，依赖管理是个永恒的话题。我见过太多团队因为依赖文件不规范而陷入"在我机器上能跑"的困境。requirements.txt不仅是包列表，更是项目可复现性的基石。
手动维护这个文件有多痛苦？每次新增依赖都要记得更新，版本冲突时得逐个比对，跨平台测试时可能发现某些包在Linux和Windows表现不同。更糟的是，当你要复现一个半年前的项目时，发现当初没记录准确的版本号。
2. 主流生成方案对比
2.1 pip freeze的利与弊
最基础的方法是使用pip freeze > requirements.txt，这会把当前环境所有已安装包及其精确版本导出。但问题很明显：
- 包含所有依赖，包括间接依赖
- 无法区分项目直接需要的包和偶然安装的包
- 生成的是固定版本，不利于后续升级
适合场景：需要完全复现环境时，比如生产部署。
2.2 pipreqs的智能识别
pipreqs会扫描项目中的import语句，只生成实际使用的包：
bash复制pip install pipreqs
pipreqs /path/to/project --force
优势：
- 只包含项目直接引用的包
- 可以通过--mode参数控制宽松/严格模式
- 支持指定排除目录
不足：
- 可能漏掉通过字符串动态导入的模块
- 不会自动包含依赖的依赖
2.3 pigar的进阶功能
pigar提供了更多实用功能：
bash复制pip install pigar
pigar -p /path/to/requirements.txt
特色：
- 生成带注释的requirements文件
- 可以检查requirements是否过期
- 支持生成setup.py格式
2.4 conda环境的导出
对于conda用户：
bash复制conda list --export > requirements.txt
# 或者带环境信息
conda env export > environment.yml
注意conda导出的文件可能包含pip不支持的格式，跨平台使用时需要检查。
3. 生产级最佳实践
3.1 分层requirements设计
我推荐的分层方案：
code复制requirements/
├── base.txt # 跨环境共享的依赖
├── dev.txt # 开发工具（测试/格式化等）
├── prod.txt # 生产环境特有配置
└── test.txt # 测试专用依赖
通过-r base.txt实现继承，例如dev.txt开头：
code复制-r base.txt
pytest==7.4.0
black==23.7.0
3.2 版本控制策略
关于版本指定，我的经验法则：
- 库项目：使用宽松约束（flask>=2.0.0）
- 应用项目：使用精确版本（flask==2.3.2）
- 测试依赖：可以允许次要版本更新
特别提醒：在Windows开发时，注意某些包（如pywin32）需要标记环境标记：
code复制pywin32==306; sys_platform == 'win32'
4. 常见问题排雷指南
4.1 环境隔离是前提
生成requirements前务必激活虚拟环境：
bash复制python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
4.2 解决跨平台差异
当出现平台特定依赖时：
- 先生成基础requirements
- 手动添加平台限定条件：
code复制pyobjc-framework-Cocoa==8.0; sys_platform == 'darwin'
4.3 处理私有仓库依赖
对于公司内部包，推荐使用--extra-index-url：
code复制--extra-index-url https://private.pypi/simple
internal-package==1.2.3
或者在pip.conf中配置永久源。
5. 自动化进阶技巧
5.1 预提交钩子自动更新
在.git/hooks/pre-commit中添加：
bash复制#!/bin/sh
pipreqs --force --mode compat .
git add requirements.txt
5.2 CI/CD集成示例
GitLab CI的自动检查阶段：
yaml复制check_deps:
stage: test
script:
- pip install pipreqs
- pipreqs --mode compat --savepath temp_req.txt
- diff requirements.txt temp_req.txt || exit 1
5.3 依赖安全扫描
结合safety检查漏洞：
bash复制pip install safety
safety check -r requirements.txt
我特别推荐在生成requirements后运行pip-compile来自动解决依赖冲突，这需要安装pip-tools包。它会生成完全锁定的版本，同时保证所有依赖兼容。