> ## 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.

# 如何创建你的 pyproject.toml 文件

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

## 用于 Python 的 pyproject.toml 文件

`pyproject.toml` 文件是一种现代方式，可在单个文件中指定项目的所有构建系统需求和依赖。本指南将展示如何创建、配置和使用 `pyproject.toml`，以确保开发环境和生产环境之间的一致性。

## 什么是 pyproject.toml 文件？

`pyproject.toml` 列出了 Python 项目的依赖、构建系统和其他元数据。这样可以：

* 让你和你的团队维护完全相同的环境
* 让新协作者精确地复现环境
* 分别配置开发依赖和生产依赖

***

<Steps>
  <Step title="创建 pyproject.toml 文件">
    首先，在项目根目录下创建一个名为 `pyproject.toml` 的文件。
  </Step>

  <Step title="定义项目详情">
    在 `pyproject.toml` 文件中，先定义你的项目元数据。我们将定义项目名称、版本、描述以及其他相关信息。\
    项目名称必须由 ASCII 字母、数字、下划线“\_”、连字符“-”和句点“.”组成。名称不能以下划线、连字符或句点开头或结尾。例如：

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="列出项目依赖">
    接下来，我们将列出项目所需的依赖。我们可以同时指定开发依赖和生产依赖。生产依赖列在 `dependencies` 部分下，而开发依赖可以列在 `optional-dependencies` 下并使用特定的组名（例如 `dev`）。\
    你可以使用比较运算符（如 `==`、`>=`、`<`……）为依赖指定版本。在下面的示例中，我们没有指定版本，这意味着将安装最新版本。
    建议指定精确版本，以确保可复现性，并防止生产环境中因不兼容的更新而出现故障。

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord-py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]
    ```
  </Step>

  <Step title="配置构建系统">
    最后，我们需要指定构建系统的需求。这对于像 pip 这样的工具了解如何构建和安装你的项目是必需的。我们将使用 `setuptools` 作为构建后端，这是 Python 项目的常见选择，但你也可以选择其他后端，如 `poetry`。

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]

    [build-system]
    requires = ["setuptools"]
    build-backend = "setuptools.build_meta"
    ```
  </Step>
</Steps>

***

## 使用 pip 安装依赖

要安装 `pyproject.toml` 文件中列出的依赖，你可以使用 pip 或其他支持 `pyproject.toml` 的工具。这样你就可以在安装好依赖的情况下开展项目工作。

```bash theme={null}
pip install .
```

此命令会读取 `pyproject.toml` 文件，安装 `dependencies` 下列出的依赖，并为开发配置好你的项目。如果你还想安装开发依赖，可以使用：

```bash theme={null}
pip install .[dev]
```

这将同时安装生产依赖和开发依赖，让你能够使用所有必要的工具开展项目工作。

## 最佳实践与技巧：

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

***

## 后续步骤

配置好 `pyproject.toml` 文件后：

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

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