> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何创建你的 requirements.txt 文件

> Python 中 requirements.txt 文件的完整指南：学习如何创建、使用 pip freeze 列出依赖、锁定版本，并为生产环境准备你的项目。

# 📋 用于 Python 的 requirements.txt 文件

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

## 什么是 requirements.txt 文件？

`requirements.txt` 文件列出了你的项目所需的所有外部 Python 包及其具体版本。这样可以：

* 让你和你的团队维护完全相同的环境
* 让新协作者精确地复现环境
* 让 Square Cloud 上的 deploy 使用正确的依赖运行

***

<Steps>
  <Step title="激活虚拟环境">
    在虚拟环境中工作对于将项目依赖与全局 Python 系统隔离开来至关重要。这可以避免版本冲突并确保可复现性。

    根据你的系统，使用下面的其中一个命令激活虚拟环境：

    **Windows：**

    ```bash theme={null}
    venv\Scripts\activate
    ```

    **macOS/Linux：**

    ```bash theme={null}
    source venv/bin/activate
    ```
  </Step>

  <Step title="列出项目依赖">
    <Warning>
      始终使用 `==` 指定精确版本，以确保可复现性，并防止生产环境中因不兼容的更新而出现故障。
    </Warning>

    ### 方案 A：手动创建（推荐）

    在项目根目录下创建一个 `requirements.txt` 文件，并列出所有外部包及其版本：

    ```plaintext requirements.txt theme={null}
    discord.py==2.3.0
    requests==2.31.0
    python-dotenv==1.0.0
    ```

    ### 方案 B：使用 pip freeze 自动生成

    在虚拟环境中安装完依赖后，你可以自动生成该文件。主要有两种方式：

    **方案 B1：使用 `pip freeze`（包含所有内容）**

    ```bash theme={null}
    pip freeze > requirements.txt
    ```

    <Warning>
      注意：`pip freeze` 会包含所有全局安装的包，其中可能包含对你的项目不必要的包。生成后请检查该文件，并移除并非严格必需的依赖。
    </Warning>

    **方案 B2：使用 `pipdeptree` 或带过滤的 `pip freeze`（推荐）**

    要仅捕获你的项目依赖（不含辅助的环境包），请使用：

    ```bash theme={null}
    pip freeze --user > requirements.txt
    ```

    或者，为了得到更干净的方案，安装 `pipdeptree`：

    ```bash theme={null}
    pip install pipdeptree
    pipdeptree -p your_project > requirements.txt
    ```

    备选方案：使用手动列表检查，或查看专门为你的项目安装了哪个包：

    ```bash theme={null}
    pip list | grep -i "your-package"
    ```

    <Note>
      如果你在虚拟环境中工作（推荐），`pip freeze` 将完美运行，因为该环境是隔离的，仅包含你的项目依赖。
    </Note>
  </Step>

  <Step title="检查并验证依赖">
    在文本编辑器中打开 `requirements.txt` 文件，然后：

    1. 检查包列表
    2. 移除不必要的依赖
    3. 按需更新版本
    4. 确保你使用的是精确版本（带 `==`）
  </Step>

  <Step title="安装依赖">
    要安装所有列出的依赖：

    ```bash theme={null}
    pip install -r requirements.txt
    ```

    此命令保证所有协作者和生产环境使用完全相同的版本。
  </Step>

  <Step title="版本控制与共享">
    准备好 `requirements.txt` 后，你可以：

    * 与你的团队共享
    * 将其纳入版本控制（git）
    * 确保每个人使用相同的版本
    * 简化在 Square Cloud 上的部署

    当你在 Square Cloud 上托管项目时，`requirements.txt` 文件会被自动检测到，并在构建过程中安装所有依赖。
  </Step>
</Steps>

***

## 💡 最佳实践与技巧：

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

***

## 🚀 后续步骤

配置好 `requirements.txt` 文件后：

1. 提交到你的 Git 仓库。
2. 在 **Square Cloud** 上托管你的项目。
3. 通过 GitHub 配置自动 deploy。
4. 欢迎来到专业的 Python 应用托管！

结构良好的 `requirements.txt` 文件是任何成功的 Python 应用的基础，确保你的应用在 Square Cloud 上完美运行。