在 Python 开发中，你是否遇到过这样的窘境：本地跑通的项目，部署到服务器就报错？同事传的代码，在你电脑上却因 “缺少模块” 无法运行？这些问题的根源，大多是依赖环境不一致。而requirements.txt，就是 Python 生态中解决依赖管理的 “标准配置”。今天这篇文章，从基础概念到实战操作，带你彻底掌握它的使用。
一、先搞懂：什么是 requirements.txt？
requirements.txt是一个纯文本文件，用于记录 Python 项目所依赖的所有第三方包及其精确版本号。它的核心作用是：
- 统一环境：确保开发、测试、生产环境使用完全相同的依赖版本，避免 “本地能跑，线上崩了” 的问题。
- 简化协作：新人接手项目时，无需手动逐个安装依赖，一条命令即可搞定所有依赖。
- 方便部署：在服务器或容器中部署项目时，快速还原依赖环境。
简单来说，它就像项目的 “依赖清单”—— 有了这份清单，无论在哪个环境，都能快速复刻出项目需要的 “运行土壤”。
二、准备工作：确保 pip 已安装（核心工具）
requirements.txt的使用完全依赖 Python 的包管理工具pip（Python Package Installer），所以第一步要确保pip已正确安装并升级到最新版。
1. 检查 pip 是否安装
打开终端（Windows 用 “命令提示符” 或 PowerShell，macOS/Linux 用 “终端”），输入以下命令：
pip –version # 或 pip3 –version（区分Python2和Python3）
如果输出类似pip 24.0 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)，说明pip已安装；若提示 “命令不存在”，则需要先安装pip。
2. 安装 / 升级 pip
pip通常随 Python 3.4 + 版本默认安装，若未安装或版本过旧，按以下步骤操作：
- Windows/macOS/Linux 通用升级命令：
# 升级pip到最新版
python -m pip install –upgrade pip
# 若系统同时有Python2和Python3，用python3指定Python3
python3 -m pip install –upgrade pip
三、核心操作：生成 requirements.txt
根据项目状态，生成requirements.txt有两种常见场景：新项目手动创建、已有项目自动生成。
场景 1：新项目（从零开始）
如果项目刚起步，依赖较少，可直接手动创建requirements.txt文件：
# 注释：项目基础依赖
flask==2.3.3 # Web框架，指定2.3.3版本
requests>=2.31.0 # HTTP请求库，最低2.31.0版本
pandas~=2.1.0 # 数据分析库，兼容2.1.x系列版本
版本号写法说明（关键！）
版本号的指定决定了依赖的兼容性，常见写法有 3 种：
- ==x.y.z：精确版本（推荐），强制安装指定版本，避免版本兼容问题。
- >=x.y.z：最低版本，安装不低于该版本的最新版，适合对版本不敏感的依赖。
- ~=x.y.z：兼容版本，允许升级到同系列的小版本（如~=2.1.0可安装 2.1.1、2.1.9，但不支持 2.2.0）。
场景 2：已有项目（自动生成，主要使用场景）
如果项目已开发一段时间，手动记录依赖太麻烦，可借助pip freeze命令自动生成requirements.txt，但有个重要前提：先激活项目的虚拟环境（否则会把全局所有 Python 包都列出来，导致文件冗余）。
步骤 1：创建并激活虚拟环境（关键！）
虚拟环境能隔离不同项目的依赖，避免全局包污染。以 Python 自带的venv为例：
# 1. 在项目根目录创建虚拟环境（venv是环境目录名，可自定义）
python -m venv venv # 或 python3 -m venv venv
# 2. 激活虚拟环境
# Windows（命令提示符）：
venv\\Scripts\\activate
# Windows（PowerShell）：
.\\venv\\Scripts\\Activate.ps1
# macOS/Linux：
source venv/bin/activate
激活成功后，终端前缀会出现(venv)，表示当前处于虚拟环境中。
步骤 2：安装项目依赖（若未安装）
在虚拟环境中，安装项目所需的所有依赖（比如pip install flask requests），确保项目能正常运行。
步骤 3：自动生成 requirements.txt
执行以下命令，将当前虚拟环境中的所有依赖（及其版本）写入requirements.txt：
pip freeze > requirements.txt
此时打开项目根目录，会发现已生成requirements.txt，内容类似：
进阶：用 pipreqs 生成更精简的依赖（推荐）
pip freeze会列出虚拟环境中的所有依赖（包括项目间接依赖的包，比如安装flask时自动安装的werkzeug），导致requirements.txt冗余。而pipreqs工具能只识别项目代码中实际导入的包，生成更精简的依赖清单。
使用 pipreqs 的步骤：
pip install pipreqs
# –encoding=utf8 解决中文注释编码问题
pipreqs . –encoding=utf8
例如，若项目代码中只导入了flask和requests，pipreqs生成的文件会只有这两个包，比pip freeze更简洁。
使用requests生成：
使用pipreqs生成：
四、核心操作：用 requirements.txt 安装依赖
当你拿到一个带有requirements.txt的项目（比如从 GitHub 下载），只需一条命令即可安装所有依赖。
步骤 1：激活虚拟环境（可选但推荐）
和生成时一样，先在项目根目录创建并激活虚拟环境（避免污染全局依赖）。
步骤 2：安装所有依赖
执行以下命令，pip会自动读取requirements.txt中的内容，安装所有指定包和版本：
pip install -r requirements.txt
常用扩展参数
- 升级依赖：如果想将依赖升级到requirements.txt指定版本范围内的最新版（需配合>=或~=写法）：
pip install –upgrade -r requirements.txt
- 使用国内镜像源（提速）：国内直接访问 PyPI 可能较慢，可指定清华、阿里等镜像源：
-
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
- 不缓存安装包（节省空间）：适合 CI/CD 或临时环境，避免缓存冗余包：
-
bash
pip install -r requirements.txt –no-cache-dir
执行命令安转之后，原有的依赖报错就被解决了。
五、进阶技巧：管理多环境依赖
实际开发中，项目可能需要区分开发环境和生产环境的依赖（比如开发时需要pytest做测试，生产环境不需要）。这时可以创建多个requirements文件。
示例：多环境依赖文件结构
plaintext
your_project/
├── requirements.txt # 生产环境依赖（核心依赖，如flask、requests）
└── requirements-dev.txt # 开发环境依赖（额外依赖，如pytest、flake8）
1. requirements.txt（生产环境）
flask==2.3.3
requests==2.31.0
pandas==2.1.0
2. requirements-dev.txt（开发环境）
# 先包含生产环境依赖
-r requirements.txt
# 再添加开发专属依赖
pytest==7.4.3 # 测试框架
flake8==6.1.0 # 代码规范检查
black==23.10.1 # 代码格式化工具
3. 安装对应环境的依赖
- 生产环境安装：pip install -r requirements.txt
- 开发环境安装：pip install -r requirements-dev.txt
六、常见问题与解决方案
问题 1：执行pip install -r时报 “版本冲突”
原因：不同依赖包对同一个子依赖的版本要求不一致（比如 A 包需要requests<2.30，B 包需要requests>=2.31）。解决方案：
问题 2：pip freeze生成的依赖太多，包含无用包
原因：未激活虚拟环境，导致全局依赖被写入。解决方案：
问题 3：Windows 下激活虚拟环境提示 “权限不足”
原因：PowerShell 默认禁止执行脚本。解决方案：
七、总结
requirements.txt看似简单，却是 Python 项目规范化、可移植的关键。掌握它的核心流程：
养成在 Python 项目中使用requirements.txt的习惯，能极大减少环境不一致带来的麻烦，让协作和部署更高效。
