在 Python 开发的世界里，项目依赖管理往往是最让人头疼，却又至关重要的一环。想象一下，当我们辛辛苦苦开发了一个项目，想要部署到服务器上，或者我们的同事想要拉取我们的代码进行协作时，如果缺少了某些特定的库，或者版本不对，程序就会立刻崩溃。为了避免这种“在我电脑上能跑，在你那就不行”的尴尬情况，我们需要一种标准化的方式来记录和安装项目所需的软件包。这就是 requirements.txt 文件大显身手的时候。
在这篇文章中，我们将深入探讨如何使用 requirements.txt 文件来优雅地管理 Python 依赖。我们不仅要回顾经典的基础用法，还要结合 2026 年的现代开发语境，看看如何在一个充斥着 Agentic AI 和 Vibe Coding 的时代，依然保持我们底层架构的稳健与高效。无论你是刚入门的编程新手，还是希望规范工作流的经验丰富的开发者，这篇指南都将为你提供实用的见解和最佳实践。
什么是 requirements.txt？
简单来说，requirements.txt 是一个纯文本文件，它充当了我们 Python 项目的“购物清单”。在这个文件中，我们列出了项目运行所需的所有外部库及其精确的版本号。通过这个文件，我们可以确保无论是在开发环境、测试环境还是生产环境中，安装的依赖包都是完全一致的。
通常，一个标准的 requirements.txt 文件看起来是这样的：
pandas==1.5.3
Pillow==9.5.0
numpy==1.24.2
requests==2.28.2
每一行代表一个包，== 符号指定了我们需要的确切版本。这种严格性对于团队协作和项目部署至关重要，因为它消除了“依赖地狱”的风险。但在 2026 年，随着项目复杂度的增加，这个文件背后的意义已经远不止于“版本锁定”，它更是我们进行 供应链安全审计 和 AI 辅助代码生成 的上下文基础。
为什么要使用 requirements.txt？
你可能会问，为什么我不能直接运行 pip install 命令呢？当然可以，但在实际的项目开发中，手动安装包存在很多隐患：
- 环境一致性：使用 requirements.txt 可以确保所有团队成员和服务器环境使用完全相同的库版本，避免因版本差异导致的 Bug。这一点在使用 Cursor 或 Windsurf 这样的 AI IDE 时尤为重要，因为 AI 上下文需要明确的环境定义才能提供准确的代码补全。
- 便捷性：它是一键安装的入口。当我们接手一个新项目时，只需运行一条命令，即可配置好所有复杂的依赖环境，而不用逐个查找和安装。
- 依赖冻结：它记录了项目特定时间点的依赖状态，这对于回溯历史版本或进行长期维护非常有帮助。
如何手动创建 requirements.txt 文件
让我们从最基础的方式开始。我们可以手动创建一个名为 requirements.txt 的文件，并将我们需要的包写进去。
步骤 1：创建文件
在你的项目根目录下，创建一个名为 requirements.txt 的文件。
步骤 2：添加依赖
打开文件，每行写一个包名。例如，假设我们的项目需要处理数据、处理图像和进行数值计算，我们可以这样写：
# 数据处理库
# 注意：我们使用兼容性发布符号，允许补丁更新，以获得安全修复
pandas~=2.2.0
# 图像处理库
pillow~=10.0.0
# 科学计算库
numpy~=1.26.0
# 异步HTTP请求，现代Python开发的标配
httpx~=0.27.0
> 实用见解：在文件中添加注释（以 # 开头）是一个非常好的习惯。在我们的实践中，详细的注释不仅能帮助人类理解，还能帮助 LLM（大语言模型） 更好地理解项目意图，从而在生成代码时选择正确的 API。
步骤 3：安装依赖
保存文件后，打开终端或命令行，确保你位于该文件所在的目录，然后运行以下命令：
# 使用 pip 读取 requirements.txt 并安装列出的所有包
# 推荐在虚拟环境中执行，以隔离项目依赖
pip install -r requirements.txt
这里的关键参数是 -r，它告诉 pip 去读取一个文件作为安装源。在我们最近的一个项目中，我们甚至将这一步骤集成到了 CI/CD 流水线的 Agent AI 脚本中，实现了依赖的自我修复。
自动生成 requirements.txt：开发者的最佳选择
虽然手动输入很有教育意义，但在实际工作中，我们通常使用 pip 的“冷冻”功能来自动生成这个文件。这是一种更安全、更准确的方法，因为它不仅记录了我们直接安装的包，还记录了这些包所依赖的“子依赖”包。
假设我们已经在当前的虚拟环境中安装好了所有需要的包，我们可以运行：
# 将当前环境中的所有包及其版本导出到文件中
# 注意：这会包含环境中所有的包，即使它们不是当前项目直接依赖的
pip freeze > requirements.txt
这会将当前 Python 环境中已安装的所有包列表写入到 requirements.txt 文件中。
进阶技巧：更清洁的依赖导出
在现代开发中，我们的开发环境往往安装了大量工具（如 pytest, black, mypy），直接使用 INLINECODE18f32ee0 会污染生产环境的依赖列表。我们强烈推荐使用 INLINECODE4a669222 工具来扫描代码并仅生成项目实际使用的依赖。
# 首先安装 pipreqs
pip install pipreqs
# 在项目根目录运行，自动扫描 .py 文件并生成 requirements.txt
# --force 参数用于覆盖已存在的文件
pipreqs . --force
这在微服务架构中特别有用，它能显著减小最终 Docker 镜像的体积。
深入解析：理解版本控制符号
在 requirements.txt 中，我们不仅仅可以使用 ==。为了更灵活地控制依赖，Python 支持多种版本标识符。理解这些符号对于高级依赖管理至关重要。
让我们通过几个例子来看看它们是如何工作的：
1. 固定版本 (==)
numpy==1.24.2
这是最严格的限制。pip 只会安装 1.24.2 版本。如果该版本不存在，安装将失败。这适用于那些绝对不能有版本变动的核心依赖，或者作为 Lockfile（锁定文件）使用。
2. 兼容发布版本 (~=) —— 2026年的推荐标准
requests~=2.28.0
这是一种非常智能的写法。INLINECODEd38cb40b 意味着“兼容性发布”。在这个例子中，它等价于 INLINECODE3ca3f389。也就是说，pip 会安装 2.28.0 或更高的版本，但必须是 2.28.x 系列。它不会跳到 2.29.0 或 3.0.0。
为什么这很重要？ 在 2026 年，安全漏洞修补频繁发布。使用 ~= 允许我们自动获取非破坏性的安全补丁（例如从 2.28.0 升级到 2.28.1），而不会因为 3.0 版本的 API 变更导致应用崩溃。这是平衡安全性与稳定性的最佳实践。
实战演练：一个完整的项目生命周期示例
为了让我们更直观地理解，让我们模拟一个实际的开发场景。我们要开发一个简单的 Web 爬虫，需要使用 INLINECODEf416d780 来获取网页，使用 INLINECODEfadcc9fd 来解析数据。
场景：初始化项目
- 首先，我们创建了项目文件夹并激活了虚拟环境。
- 我们手动安装了我们需要的包：
pip install httpx beautifulsoup4
- 工作完成后，我们准备提交代码。此时，我们需要生成依赖文件。我们使用
pip freeze来确保所有的子依赖都被捕获：
pip freeze > requirements.txt
生成的 requirements.txt 可能长这样：
beautifulsoup4==4.12.2
certifi==2023.7.22
httpx==0.27.0
idna==3.4
soupsieve==2.5
> 注意：你会发现这里多出了很多我们没有手动安装的包，比如 INLINECODEf4ba5ba3、INLINECODE240207f2 等。这是因为 INLINECODE6b71604d 库依赖于它们才能正常工作。INLINECODE2aef29c5 非常贴心地帮我们把这些“隐藏”的依赖也记录下来了。
场景：克隆项目到新环境
现在，你的同事克隆了你的代码库。他不需要去猜你用了哪些库，他只需要运行：
# 进入项目目录
cd my-scraper-project
# 安装所有依赖（建议在虚拟环境中）
pip install -r requirements.txt
几秒钟后，他的环境配置就和你完全一致了，项目可以立即运行。这就是标准化的力量。
常见问题与解决方案 (Troubleshooting)
在实际操作中，你可能会遇到一些棘手的问题。让我们看看如何解决它们。
问题 1：安装速度慢或超时
默认情况下，pip 从官方的 PyPI 源下载包。由于网络原因，这可能会非常慢。
解决方案：我们可以使用国内的镜像源来加速，或者配置全局源。
# 使用清华镜像源安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
在现代开发中，我们通常会在 CI/CD 流水线中配置多个镜像源作为回退机制，以确保构建的高可用性。
问题 2：依赖冲突
当项目变得复杂时，可能会出现包 A 需要 INLINECODE07e9e7c7，而包 B 需要 INLINECODE7eab07aa 的情况。
解决方案：这是单纯的 requirements.txt 难以解决的痛点。在 2026 年，如果遇到这种情况，我们强烈建议放弃直接编辑 requirements.txt，转而使用 Poetry 或 PDM 等现代包管理器。它们使用 pyproject.toml 并内置了强大的依赖解析算法，能够自动处理这类冲突。但如果必须使用 pip，我们可以尝试：
# 尝试升级相互冲突的包到最新兼容版本
pip install --upgrade --force-reinstall -r requirements.txt
2026 前瞻：超越 requirements.txt 的现代工程化
虽然 requirements.txt 是 Python 生态的基石，但在 2026 年的技术 landscape 中，我们需要看到它的局限性，并结合更先进的技术。
1. 生成式 AI 与依赖管理
现在，当我们使用 GitHub Copilot 或 Cursor 时，AI 可以通过分析我们的代码自动生成 requirements.txt。我们可以在 IDE 中直接输入提示词：“/generate requirements based on my imports”。这不仅是效率的提升，更是减少了人为疏忽（例如忘记记录某个间接依赖）。
2. 容器化与不可变基础设施
在现代部署中，我们很少再在生产服务器上直接运行 INLINECODE4367358e。标准的做法是将 INLINECODE0f44969e 这一步骤封装在 Dockerfile 中。这不仅确保了环境的一致性，还让我们能够利用多层缓存来加速构建。
# 2026年的标准 Dockerfile 写法
FROM python:3.13-slim
WORKDIR /app
# 先复制依赖文件，利用 Docker 缓存层
COPY requirements.txt .
# 安装依赖，--no-cache-dir 确保镜像更小
RUN pip install --no-cache-dir -r requirements.txt
# 复制源代码
COPY . .
CMD ["python", "main.py"]
3. 安全左移
依赖包是供应链攻击的主要目标。在提交 requirements.txt 之前，我们建议使用 pip-audit 工具进行扫描：
pip install pip-audit
pip-audit -r requirements.txt
这在大型企业级项目中是必不可少的步骤，它能帮我们识别出含有已知漏洞的包版本。
总结与最佳实践
通过这篇文章，我们不仅学习了 pip install -r requirements.txt 这条命令，更深入理解了现代 Python 项目中依赖管理的哲学，以及它如何适应 2026 年的开发趋势。
关键要点回顾：
- 标准化：requirements.txt 依然是 Python 生态中共享依赖的标准方式，是所有高级工具的基础。
- 版本控制：合理使用 INLINECODEfe654a8f、INLINECODE20093286 和 INLINECODEbb3204cf 来平衡稳定性与灵活性。推荐在生产环境中倾向于 INLINECODEdcdf5f5b。
- 自动化：使用 INLINECODEc1057d8a 或 INLINECODEf53c8315 自动生成文件，利用 AI 工具进行审查。
- 分离关注点：创建
requirements-dev.txt来分离开发和生产依赖，保持生产环境的精简。
实用的后续步骤：
在你的下一个项目中，尝试将这些步骤纳入你的工作流：
- 开始编码前，先创建一个虚拟环境。
- 每安装一个新的包，都要思考它是否应该被记录。
- 提交代码前，务必运行
pip freeze > requirements.txt并检查变动。 - 尝试使用
pip-audit扫描一次你的依赖文件，看看有没有潜在的安全隐患。
掌握依赖管理是迈向专业 Python 开发者的必经之路。希望这篇文章能帮助你更好地组织和管理你的项目，让你在这个充满 AI 辅助和云原生架构的时代，依然能够写出健壮、可靠的代码。祝你编码愉快！