构建 Python 应用

Buildpack 通过环境变量支持语言惯用配置。

指定 Python 版本

默认情况下，Python 运行时 Buildpack 使用最新的稳定版 Python 解释器。如果您的应用需要使用特定版本，您可以通过在应用的根目录中添加 .python-version 文件来指定版本。

3.14

使用 GOOGLE_PYTHON_VERSION

还可以通过 GOOGLE_PYTHON_VERSION 环境变量指定 Python 版本。如果同时设置了这两个配置，则 GOOGLE_PYTHON_VERSION 值优先于 .python-version 文件。默认情况下，如果未指定 .python-version 文件和 GOOGLE_PYTHON_VERSION 环境变量，则使用最新的 LTS 版本的 Python。

要在部署应用时将 Buildpack 配置为使用 Python 3.13，请运行以下命令：

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.14.x"

您还可以使用 project.toml 项目描述符对环境变量以及项目文件进行编码。请参阅使用环境变量构建应用中的说明。

指定依赖项

使用以下任一方法，为受支持的 Python 版本指定应用依赖项：

• 在根目录中使用 requirements.txt 文件。此文件必须与包含源代码的 main.py 文件位于同一目录中。在 requirements.txt 文件中，每个软件包对应一行内容。每行包含软件包名称和（可选）请求的版本。为了防止 build 受到依赖项版本更改的影响，请考虑将依赖项软件包固定到特定版本。

  下面是一个 requirements.txt 文件示例：

  functions-framework
  requests==2.20.0
  numpy
  

• 使用 pyproject.toml 文件指定依赖项。如果您在 pyproject.toml 文件中（而不是在 requirements.txt 文件中）管理应用依赖项，则 Python buildpack 会根据您在 pyproject.toml 文件中指定的配置来确定软件包管理系统。如需了解详情，请参阅使用 pyproject.toml 文件部署 Python 应用。

  如果您的应用同时使用 pyproject.toml 文件和 requirements.txt 文件，则 requirements.txt 文件的优先级更高。

  • 下面是一个 pyproject.toml 文件示例：

    [project]
    name = "demo-app"
    version = "0.1.0"
    description = ""
    requires-python = ">=3.10"
    dependencies = [
        "flask>=3.1.1",
        "gunicorn>=23.0.0",
    ]
    
    [build-system]
    requires = ["setuptools>=61.0"]
    build-backend = "setuptools.build_meta"
    

软件包管理器

如果您使用 requirements.txt file 管理依赖项，默认的软件包管理系统会因您配置的 Python 版本而异。

如果您使用 pyproject.toml 文件（而非 requirements.txt 文件）来管理依赖项，Python buildpack 会根据 pyproject.toml 文件中的配置设置来确定软件包管理系统。buildpack 支持 pip、uv 和 Poetry 软件包管理系统。如需了解详情，请参阅使用 pyproject.toml 文件部署 Python 应用。

Python 3.14 及更高版本

从 Python 3.14 版（预览版）开始，Python buildpack 使用 uv 软件包管理系统作为您在 requirements.txt 文件中指定的依赖项的默认安装程序。

如需使用 pip 作为软件包管理系统，请配置环境变量 GOOGLE_PYTHON_PACKAGE_MANAGER="pip"。

Python 3.13 及更低版本

对于 Python 3.13 版及更低版本，Python buildpack 会使用 pip 软件包管理系统来安装您在 requirements.txt 文件中定义的依赖项。

如需使用 uv（预览版）作为软件包管理系统，请配置环境变量 GOOGLE_PYTHON_PACKAGE_MANAGER="uv"。

配置 pip

您可以使用环境变量配置 pip 的行为：

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

来自 Artifact Registry 的专用依赖项

Artifact Registry Python 代码库可以为您的 Python 函数托管专用依赖项。在 Cloud Build 上构建应用时，Python Buildpack 会自动为 Cloud Build 服务账号生成 Artifact Registry 凭据。您只需在 requirements.txt 中添加 Artifact Registry 网址，而不需要生成其他凭据。例如：

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

应用入口点

以下部分介绍了 Python buildpack 的默认入口点。

Cloud Run 源代码部署的入口点

只有在您使用 Python 运行时将源代码部署到 Cloud Run 时，此功能才可用。如果您在 Cloud Run 源代码部署流程之外直接使用 pack build 构建容器映像，则此功能不适用。

Python buildpack 支持 FastAPI、Gradio 和 Streamlit 等现代 Web 框架。

Python 3.12 版及更低版本

如果您使用的是 Python 3.12 版及更低版本，则 Python Buildpack 默认使用 Gunicorn 作为工作负载的 WSGI HTTP 服务器。Python Buildpack 会将默认入口点设置为 gunicorn -b :8080 main:app。

Python 3.13 版及更高版本

对于 Python 3.13 版及更高版本，Python Buildpack 会根据 requirements.txt 文件中的 Web 服务器或框架配置，为 Cloud Run 源代码部署设置默认入口点。此默认设置仅适用于 Cloud Run 服务源代码部署，而不适用于 Cloud Run 函数。

当您使用 Python 运行时从源代码部署 Cloud Run 服务时，buildpack 会通过以下方式确定 Python 版本和默认入口点：

• 如果您未在源代码文件中指定 Python 版本，则 Python buildpack 会将默认版本设置为最新受支持的 Python 版本。Buildpack 会根据您在 requirements.txt 文件中配置的Web 服务器或框架来确定默认入口点。

• 如果您未在 requirements.txt 文件中指定 Web 服务器或框架，则 Python buildpack 默认使用 Gunicorn 作为工作负载的 WSGI HTTP 服务器。Python Buildpack 会将默认入口点设置为 gunicorn -b :8080 main:app。

• Python Buildpack 会根据 requirements.txt 文件中定义的以下优先级顺序设置默认入口点：

  1. gunicorn
  2. uvicorn
  3. fastapi[standard]
  4. gradio
  5. streamlit

配置 Web 服务器或框架

对于 requirements.txt 文件中的每种常见 Python 配置，下表显示了从源代码部署到 Cloud Run 时的默认入口点：

主要配置	默认入口点	环境变量
gunicorn	gunicorn -b :8080 main:app
numpy	gunicorn -b :8080 main:app
fastapi uvicorn	uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard]	uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn gunicorn	gunicorn -b :8080 main:app
gradio	python main.py	GRADIO_SERVER_NAME=0.0.0.0 GRADIO_SERVER_PORT=8080
streamlit	streamlit run main.py --server.address 0.0.0.0 --server.port 8080

为避免部署失败，请在源代码文件中使用受支持的 Python 版本，并在 requirements.txt 文件中指定 Web 服务器。

或者，您也可以通过运行以下源代码部署命令来指定入口点：

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

替换以下内容：

• SERVICE：您要部署到的服务的名称。
• ENTRYPOINT：您要用于源代码的默认入口点。

如果您无法将源代码部署到 Cloud Run 或在日志中发现错误，请参阅 Cloud Run 问题排查指南。

所有其他部署的入口点

Python Buildpack 会将 Gunicorn 用作工作负载的默认 WSGI HTTP 服务器。使用 Python Buildpack 构建的应用会使用默认设置启动 gunicorn 进程，类似于运行以下命令：

gunicorn --bind :8080 main:app

自定义应用入口点

您可以使用 Procfile 或环境变量自定义应用的启动命令。您可能需要这样做来自定义默认入口点配置。

您可以使用自定义设置在根目录中创建 Procfile。示例：

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

重要提示：替换 Gunicorn 默认值时，您必须在项目的 requirements.txt 文件中添加 gunicorn 作为软件包依赖项。

或者，您也可以将 GOOGLE_ENTRYPOINT 环境变量与 pack 命令搭配使用。示例：

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

环境变量

Python Buildpack 支持使用以下环境变量来自定义容器

PIP_<key>

请参阅 pip 文档。

示例：PIP_DEFAULT_TIMEOUT=60 为 pip 命令设置 --default-timeout=60。

使用 pyproject.toml 文件部署 Python 应用

预览版 — Deploy Python applications to Cloud Run and Cloud Run functions with a pyproject.toml file

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

Python buildpack 支持您使用 pyproject.toml 文件配置的项目。借助此功能，您可以将使用 Poetry、uv 或 pip 管理的应用直接部署到 Cloud Run 和 Cloud Run functions。App Engine 不支持此功能。

仅当根目录中没有 requirements.txt 文件时，Python buildpack 才会使用 pyproject.toml 文件。如果您的应用同时使用 pyproject.toml 文件和 requirements.txt 文件，则 requirements.txt 文件的优先级更高。

支持的 buildpack 配置

Python buildpack 支持以下配置：

• pip buildpack：如果检测到以下所有条件，则直接从 pyproject.toml 安装依赖项：

  • 根目录中存在 pyproject.toml 文件，并且您未配置高优先级工具，例如 poetry.lock 文件、[tool.poetry] 部分或 uv.lock 文件。

  • 您将 GOOGLE_PYTHON_PACKAGE_MANAGER 环境变量设置为 pip。

• uv buildpack：支持您使用 uv 管理的 Python 项目。如果检测到以下任何条件，则会激活此 buildpack：

  • 项目根目录中存在 uv.lock 文件和 pyproject.toml 文件。
  • 项目根目录中存在 pyproject.toml 文件，并且您将 GOOGLE_PYTHON_PACKAGE_MANAGER 环境变量设置为 uv。
  • 存在 pyproject.toml 文件，并且您未包含其他高优先级的锁定文件（例如 poetry.lock、uv.lock）或配置（例如 [tool.poetry]），并且未设置 GOOGLE_PYTHON_PACKAGE_MANAGER 环境变量。

• Poetry buildpack：支持您使用 Poetry 管理的 Python 项目。如果检测到以下任何条件，则会激活此 buildpack：

  • 项目根目录中存在 poetry.lock 文件和 pyproject.toml 文件。
  • 项目根目录中存在 pyproject.toml 文件，并且 pyproject.toml 文件中存在 [tool.poetry] 部分。

软件包管理系统的优先级

Python buildpack 会根据配置按以下优先顺序确定默认的软件包管理系统：

1. requirements.txt 文件具有最高优先级。只有当此文件存在时，Python buildpack 才会在构建步骤中使用默认软件包管理系统安装依赖项。如果不存在 requirements.txt 文件，检测过程将进入下一步。

2. 然后，buildpack 会检查 pyproject.toml 文件中是否存在 poetry.lock 文件或 [tool.poetry] 部分。如果找到，构建流程会继续使用 Poetry 安装依赖项。

3. 如果未检测到 Poetry 配置，buildpack 会检查是否存在 uv.lock 文件。如果找到，构建流程会继续使用 uv 来安装依赖项。

4. 如果不存在锁定文件，buildpack 会检查 GOOGLE_PYTHON_PACKAGE_MANAGER 环境变量中是否存在 pip 或 uv 配置。

5. 默认值。如果您未设置环境变量，并且仅使用不含 uv 或 Poetry 的 pyproject.toml 文件，则 buildpack 默认使用 uv 处理所有受支持的 Python 版本。

使用 pyproject.toml 文件的入口点

如果您使用 pyproject.toml 文件而不是 requirements.txt 文件来部署应用，则 Python buildpack 会使用其他方法来确定入口点。如需了解如何使用 requirements.txt 文件配置应用入口点，请参阅应用入口点。

buildpack 会按以下优先顺序搜索入口点：

1. 如果根目录中存在 Procfile，或者您配置了 GOOGLE_ENTRYPOINT 环境变量，则这些配置始终会替换由 pyproject.toml 脚本确定的任何入口点。

2. Python buildpack 会利用您在 [tool.poetry.scripts] 和 [project.scripts] 部分中配置的自定义脚本。如果您配置的脚本包含 start，则此脚本即为您的入口点。 例如，poetry run start 或 uv run start。

3. 如果您未配置 start 脚本，但定义了其他脚本，则您定义的脚本即为默认入口点。例如 poetry run mycmd 或 uv run mycmd。

与基于 requirements.txt 的 build 不同，Python buildpack 不会自动为 pyproject.toml 项目安装 gunicorn。如需使用 gunicorn 或任何其他服务器，您必须将其明确添加到 pyproject.toml 文件中的依赖项。

如果您未在 pyproject.toml 文件中配置自定义脚本，buildpack 会尝试从 pyproject.toml 依赖项中检测常用框架（例如 gunicorn、uvicorn 或 fastapi），并确定默认入口点。