分享python项目与开源python项目中的效率法宝--requirements文件的使用

告别"在我电脑上能跑"的魔咒，用一份文件锁定整个项目环境

你有没有过这样的经历：

从 GitHub 上 clone 下一个热门的开源项目，满心欢喜地跑起来，结果终端跳出一片红字 ModuleNotFoundError: No module named 'xxx'，你开始手动一个个安装，装到一半发现版本冲突，项目死活跑不起来。
你把自己的项目发给同事，对方兴冲冲地尝试，结果报了一堆错，你在他电脑上鼓捣半天才搞定，最后发现是因为你的环境里有个包没写进文档。
你几个月前写的一个脚本，今天换台电脑想跑一下，结果因为忘了当时装过哪些依赖，连第一步都迈不出去。

这些场景，几乎每个 Python 开发者都遇到过。问题出在哪里？依赖环境没有记录和锁定。

今天，我们就来聊聊解决这个问题的"法宝"------requirements.txt。它简单、轻量、通用，却能在项目分享、协作、部署中大幅提升效率，让你把精力真正放在业务逻辑上。

一、痛点解剖：为什么我们需要依赖管理？

Python 项目几乎不可能脱离第三方库。无论是 requests 发请求、flask 写后端，还是 pandas 处理数据，依赖无处不在。每个库又有自己的依赖，形成了错综复杂的依赖树。

如果你不把这些依赖记录下来，或者只记录名字不记录版本，就会出现：

环境不一致：你的电脑里可能已经全局安装了 A、B、C 三个包，但别人的电脑上可能一个都没有，或者版本不同。结果就是"我电脑上能跑，你电脑上跑不了"。
版本冲突：项目依赖的两个库，对同一个底层库有不同版本要求，导致安装失败或运行时崩溃。
生产事故 ：开发时用的是 flask==1.1.4，部署时 pip 自动安装了最新的 flask==2.3.0，接口行为变了，线上直接 500。
交接困难：接手别人的代码，没有依赖说明，只能靠报错信息一点一点猜，耗时耗力。

这些问题，用一个 requirements.txt 文件就能解决大半。

二、requirements.txt 是什么？

它是一个纯文本文件，通常放在项目根目录，里面列出了项目所需要的所有 Python 包及其版本信息。例如：

复制代码

requests==2.28.1
Flask>=2.0.0,<3.0.0
numpy

== 表示固定版本，保证精确复现
>=、<=、~= 等表示版本范围（生产环境慎用）
不写版本号，则默认安装最新版（强烈不推荐用于生产）

这个文件就像一张购物清单，告诉别人：要运行这个项目，请安装这些包。

三、核心用法：生成与安装

生成 requirements.txt

在虚拟环境中，当你安装好项目所有依赖后，执行：

bash 复制代码

pip freeze > requirements.txt

pip freeze 会列出当前环境中所有已安装的包及其精确版本，然后 > 将输出写入 requirements.txt。

⚠️ 注意：千万不要在全局 Python 环境执行这个命令，否则会导出全局安装的所有包，让文件变得臃肿且包含无关依赖。

安装依赖

当别人拿到你的项目后，在对应的虚拟环境中执行：

bash 复制代码

pip install -r requirements.txt

一条命令，所有依赖自动安装，环境瞬间复现。

如果网络慢，可以临时指定国内镜像源加速：

bash 复制代码

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

四、最佳实践：虚拟环境 + requirements.txt

为什么必须用虚拟环境？

虚拟环境为每个项目创建一个独立的 Python 环境，项目之间的依赖互不干扰。没有虚拟环境，所有项目共享全局环境，迟早会乱。

操作步骤（以 venv 为例）

bash 复制代码

# 1. 进入项目目录
cd myproject

# 2. 创建虚拟环境（命名为 venv）
python -m venv venv

# 3. 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. 安装项目依赖（假设你已经在虚拟环境中手动安装好了所需的包）
pip install flask requests pandas

# 5. 导出依赖清单
pip freeze > requirements.txt

# 6. 将 requirements.txt 提交到代码仓库
git add requirements.txt
git commit -m "Add requirements.txt"

对方拿到代码后，只需要：

bash 复制代码

cd myproject
python -m venv venv
source venv/bin/activate   # 或 Windows 对应命令
pip install -r requirements.txt

环境就完全一致了。

五、进阶技巧：让 requirements.txt 更强大

1. 区分开发与生产依赖

有些包只在开发时需要（如 pytest、black），不应该出现在生产环境。可以拆分成两个文件：

requirements.txt：生产依赖（Flask, requests 等）
requirements-dev.txt：开发依赖，内容为 -r requirements.txt 加上开发工具：

-r requirements.txt
pytest==7.2.0
black==23.1.0

开发时安装：pip install -r requirements-dev.txt；生产环境只用 requirements.txt。

2. 锁定精确版本，杜绝意外升级

pip freeze 导出的版本都是精确的（如 requests==2.28.1）。这样，无论何时执行 pip install -r requirements.txt，都会安装完全相同的版本。这保证了环境的一致性，是生产环境的基石。

如果你的 requirements.txt 只写了包名或宽松范围，那么不同时间安装可能得到不同版本，很可能引入不兼容的变化。

3. 支持 Git 仓库或本地包

如果你的项目依赖了私有 Git 仓库或本地开发的包，requirements.txt 也支持：

复制代码

git+https://github.com/user/repo.git@branch#egg=package
./path/to/local/package

这在团队开发或微服务场景中非常实用。

4. 加速安装：使用镜像源

国内访问 PyPI 官方源可能较慢，可以配置 pip 使用清华、阿里等镜像源。临时使用：

bash 复制代码

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

也可以永久配置，在用户目录下创建 pip.ini (Windows) 或 pip.conf (macOS/Linux)。

六、从 requirements.txt 走向更现代的工具

requirements.txt 简单、通用，适用于绝大多数中小型项目。但随着项目规模增长，你可能需要更强大的依赖管理：

pip-tools ：通过 requirements.in 定义直接依赖，自动生成精确锁定的 requirements.txt，解决了 pip freeze 无法区分直接依赖和间接依赖的问题。
Poetry ：新一代依赖管理工具，自动创建虚拟环境、解析依赖、锁定版本，并生成 pyproject.toml，体验更优雅。
Pipenv ：结合 pip 和 virtualenv，使用 Pipfile 和 Pipfile.lock，也是不错的选择。

不过，无论你以后使用哪种高级工具，理解 requirements.txt 的原理始终是最基础的能力。它就像自行车，简单可靠，是学习更复杂工具的起点。

七、总结：效率从规范开始

痛点：环境不一致，项目难以分享和复现。
解决方案 ：虚拟环境 + requirements.txt。
核心流程 ：
1. 创建并激活虚拟环境
2. 安装依赖
3. pip freeze > requirements.txt
4. 分享文件，他人通过 pip install -r requirements.txt 复现环境
最佳实践 ：
- 每个项目独立虚拟环境
- 生产环境锁定精确版本
- 区分开发和生产依赖
- 使用镜像源加速安装
进阶：了解 pip-tools、Poetry 等工具，按需升级

从今天起，养成每个 Python 项目都使用虚拟环境和 requirements.txt 的习惯。你会发现，原来分享代码、协作开发、部署上线可以如此顺畅。

一份 requirements.txt，省去无数沟通和排错的时间，这才是真正的效率法宝。

你还在等什么？赶紧去给你的项目加上这份"环境说明书"吧！