Skip to main content
requirements.txt 文件是 Python 项目中指定和管理依赖的行业标准。本指南将展示如何创建、配置和使用 requirements.txt，以确保开发环境和生产环境之间的一致性。

​
什么是 requirements.txt 文件？

requirements.txt 文件列出了你的项目所需的所有外部 Python 包及其具体版本。这样可以：
  • 让你和你的团队维护完全相同的环境
  • 让新协作者精确地复现环境
  • 让 Square Cloud 上的 deploy 使用正确的依赖运行
1

创建并激活虚拟环境

在虚拟环境中工作对于将项目依赖与全局 Python 系统隔离开来至关重要。这可以避免版本冲突并确保可复现性。在项目根目录下创建虚拟环境（如果在 macOS/Linux 上找不到 python，请使用 python3）：
根据你的系统，使用下面的其中一个命令激活它：Windows：
macOS/Linux：
然后安装你的项目使用的包，例如：
2

列出项目依赖

始终使用 == 指定精确版本，以确保可复现性，并防止生产环境中因不兼容的更新而出现故障。

​
方案 A：使用 pip freeze 生成（推荐）

在已激活虚拟环境的情况下，将每个已安装的包及其精确版本写入该文件：
在虚拟环境中，pip freeze 只会列出安装在该环境中的包（你的依赖及其子依赖），并且已经用 == 固定了版本。
在虚拟环境之外，pip freeze 会列出你系统上安装的所有包。请检查该文件，并移除你的项目未使用的包。

​
方案 B：手动创建

在项目根目录下创建一个 requirements.txt 文件，并列出你的项目使用的包及其版本：
requirements.txt
3

检查并验证依赖

在文本编辑器中打开 requirements.txt 文件，然后：
  1. 检查包列表
  2. 移除不必要的依赖
  3. 按需更新版本
  4. 确保你使用的是精确版本（带 ==）
4

安装依赖

要安装所有列出的依赖：
此命令保证所有协作者和生产环境使用完全相同的版本。
5

版本控制与共享

准备好 requirements.txt 后，你可以：
  • 与你的团队共享
  • 将其纳入版本控制（git）
  • 确保每个人使用相同的版本
  • 简化在 Square Cloud 上的部署
当你在 Square Cloud 上托管项目时，requirements.txt 文件会被自动检测到，并在应用启动之前通过 pip install -r requirements.txt 安装其中的依赖。

​
最佳实践与技巧

  • 保持更新：在添加新依赖时，定期检查并更新 requirements.txt
  • 使用精确版本：始终使用 ==，而不是 >、>= 或不指定版本，以避免生产环境中的意外
  • 检查 pip freeze：如果使用 pip freeze，请在提交前检查该文件，因为它可能包含不必要的辅助包
  • 版本控制：将 requirements.txt 提交到 git，以跟踪依赖变更
  • 隔离环境：为每个项目维护一个虚拟环境，以避免全局冲突
  • 本地测试：在部署之前，在一个新环境中使用 pip install -r requirements.txt 测试该文件

​
后续步骤

配置好 requirements.txt 文件后：
  1. 将它提交到你的 Git 仓库。
  2. 通过 Python 运行时指南 托管你的项目，或参阅框架指南：Django、Flask 或 FastAPI。
  3. 每次推送时从 GitHub 自动部署。