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

​
什么是 pyproject.toml 文件？

pyproject.toml 列出了 Python 项目的依赖、构建系统和其他元数据。这样可以：
  • 让你和你的团队维护完全相同的环境
  • 让新协作者精确地复现环境
  • 分别配置开发依赖和生产依赖
1

创建 pyproject.toml 文件

首先，在项目根目录下创建一个名为 pyproject.toml 的文件。
2

定义项目详情

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

列出项目依赖

接下来，我们将列出项目所需的依赖。我们可以同时指定开发依赖和生产依赖。生产依赖列在 dependencies 部分下，而开发依赖可以列在 optional-dependencies 下并使用特定的组名（例如 dev）。
你可以使用比较运算符（如 ==、>=、<……）为依赖指定版本。在下面的示例中，每个依赖都用 == 固定到了一个精确版本。 建议指定精确版本，以确保可复现性，并防止生产环境中因不兼容的更新而出现故障。
pyproject.toml
4

配置构建系统

最后，我们需要指定构建系统的需求。这对于像 pip 这样的工具了解如何构建和安装你的项目是必需的。我们将使用 setuptools 作为构建后端，这是 Python 项目的常见选择，但你也可以选择其他后端，如 poetry。 [tool.setuptools] 下的 py-modules = [] 这一行告诉 setuptools 没有需要打包的模块，因此 pip install . 只会安装依赖。如果没有这一行，包含多个顶层文件夹（例如 cogs/ 和 utils/）的应用会失败并报错 Multiple top-level packages discovered in a flat-layout。
pyproject.toml

​
使用 pip 安装依赖

要安装 pyproject.toml 文件中列出的依赖，你可以使用 pip 或其他支持 pyproject.toml 的工具。这样你就可以在安装好依赖的情况下开展项目工作。
此命令会读取 pyproject.toml 文件，安装 dependencies 下列出的依赖，并为开发配置好你的项目。当你的上传内容中有 pyproject.toml 而没有 requirements.txt 时，Square Cloud 运行的也是这个命令。如果你还想安装开发依赖，可以使用：
这将同时安装生产依赖和开发依赖，让你能够使用所有必要的工具开展项目工作。

​
最佳实践与技巧

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

​
后续步骤

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