在 Python 中指定依附元件

使用下列任一方法，為支援的 Python 版本指定應用程式依附元件：

  • 使用根目錄中的 requirements.txt 檔案。這個檔案必須與包含原始碼的 main.py 檔案位在同一目錄。requirements.txt 檔案中，一行代表一個套件，每行都包含套件名稱以及要求的版本。為避免建構作業受到依附元件版本變更影響，建議將依附元件套件固定在特定版本。

    以下是 requirements.txt 檔案範例：

    functions-framework
requests==2.20.0
numpy

  • 使用 pyproject.toml 檔案指定依附元件。如果您在 pyproject.toml 檔案中管理應用程式依附元件，而非 requirements.txt 檔案，Python 建構套件會根據您在 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"

  • 封裝本機依附元件和函式。

    系統不支援使用 Pipfile/Pipfile.lock 標準指定依附元件。專案不應包含這些檔案。

    如果您使用 requirements.txt 檔案管理依附元件，建立函式時，Cloud Run 會代您安裝 Functions Framework。不過，我們建議您將 Functions Framework 納入明確的依附元件，以免發生差異。

    使用 pyproject.toml 檔案時，您必須將 Functions Framework 做為依附元件納入，因為 Cloud Run 不會代您安裝。

套件管理工具

如果您使用 requirements.txt file 管理依附元件，預設套件管理工具會因您設定的 Python 版本而異。

如果您使用 pyproject.toml 檔案管理依附元件，而非 requirements.txt 檔案，Python 建構套件會根據 pyproject.toml 檔案中的設定，判斷套件管理員。建構包支援 pip、uv 和 Poetry 套件管理工具。詳情請參閱「使用 pyproject.toml 檔案部署 Python 應用程式」。

Python 3.14 以上版本

從 Python 3.14 版 (預覽版) 開始，Python 建構包會使用 uv 套件管理工具，做為您在 requirements.txt 檔案中指定依附元件的預設安裝程式。

如要使用 pip 做為套件管理員，請設定 GOOGLE_PYTHON_PACKAGE_MANAGER="pip" 環境變數。

執行 gcloud run deploy 指令，將套件管理員環境變數設為 pip：

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=pip

將 SERVICE 替換為 Cloud Run 服務名稱。

Python 3.13 以下版本

如果是 Python 3.13 版和更早版本，Python 建構套件會使用 pip 套件管理工具，安裝您在 requirements.txt 檔案中定義的依附元件。

如要使用 uv (搶先版) 做為套件管理工具，請設定環境變數 GOOGLE_PYTHON_PACKAGE_MANAGER="uv"。

執行 gcloud beta run deploy 指令，將套件管理員環境變數設為 uv：

gcloud beta run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=uv

將 SERVICE 替換為 Cloud Run 服務名稱。

封裝本機依附元件

將依附元件與函式一起封裝及部署。如果您使用支援的套件管理工具時，相依元件無法使用，或是 Cloud Run 環境的網際網路存取權受到限制，這個方法就非常實用。

您也可以使用 requirements.txt 檔案指定尚未與函式一起封裝的其他依附元件。舉例來說，您可以使用下列目錄結構：

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

使用下列 import 陳述式，從 localpackage 匯入程式碼：

# code in main.py
from localpackage import script

這種做法不會執行任何 setup.py 檔案。您可以將套件與這些檔案組合在一起，但套件可能無法在 Cloud Run functions 上正常執行。

複製的依附元件

複製的依附元件是指來源直接納入原始碼套件，並與您自己的程式碼一起重建的依附元件。使用 GOOGLE_VENDOR_PIP_DEPENDENCIES 建構環境變數建立複製的 pip 依附元件，並避免在部署期間安裝這些依附元件。

建立複製的依附元件

  1. 確認開發系統已安裝 python3。

  2. 在開發樹狀結構的根目錄中，於 requirements.txt 檔案中宣告應用程式依附元件。

  3. 在 requirements.txt 檔案中，將 functions-framework 分行列出，即可將 Functions Framework 宣告為必要條件。

  4. 將函式的依附元件下載到本機目錄。具體步驟取決於依附元件是 Python wheel (*.whl) 檔案還是 tar 檔案 (*.tar.gz)。

    1. 如果依附元件是 Python Wheel (*.whl)，請使用下列 pip 指令，將其下載至開發樹狀結構的根目錄：

      python3 -m pip download -r requirements.txt --only-binary=:all: \
   -d DIRECTORY \
   --python-version PYTHON_RUNTIME_VERSION \
   --platform manylinux2014_x86_64 \
   --implementation cp

      更改下列內容：

      • DIRECTORY：要下載至的本機目錄名稱。
      • PYTHON_RUNTIME_VERSION：用於相容性檢查的 Python 版本。例如 Python 3.14 的 314。
        這個版本必須與其中一個支援的 Python 執行階段相符。

      產生的目錄結構應如下所示： 

      myfunction/
├── main.py
└── requirements.txt
└── DIRECTORY
   ├── dependency1.whl
   └── dependency2.whl

    2. 如果依附元件是 tar 檔案 (*.tar.gz)：

      1. 如果依附元件是以 Python 編寫，請使用 pip 下載：

        python3 -m pip download -r requirements.txt \
   -d DIRECTORY

      2. 如果依附元件包含以 C 或 C++ 撰寫的程式碼，請分別下載及編譯程式碼。

  5. 部署函式和複製的依附元件：

    gcloud functions deploy FUNCTION_NAME \
  --runtime PYTHON_RUNTIME_NAME \
  --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY

    更改下列內容：

    • FUNCTION_NAME：要部署的函式名稱。
    • PYTHON_RUNTIME_NAME：其中一個支援的 Python 執行階段名稱，用於執行部署的函式，例如 python311。這必須與您在本機開發環境中使用的 Python 執行階段版本相同。
    • DIRECTORY：包含所複製依附元件的目錄名稱。

如要進一步瞭解如何使用建構包，請參閱「使用建構包建構函式」。

使用私人依附元件

您可以從 Artifact Registry 或其他存放區使用私人依附元件。

Artifact Registry 中的私有依附元件

Artifact Registry Python 存放區會代管 Python 函式的私有依附元件。部署至 Cloud Run 時，建構程序會自動為 Cloud Build 服務帳戶產生 Artifact Registry 憑證。在 requirements.txt 中加入 Artifact Registry 網址，不必產生額外憑證。例如：

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

如果建構作業需要多個存放區，請使用 Artifact Registry 虛擬存放區，安全地控管 pip 搜尋存放區的順序。

其他存放區的私有依附元件

Buildpack 會在 Cloud Build 環境中安裝依附元件，該環境無法提供 SSH 金鑰的存取權。複製您託管在需要 SSH 型驗證的存放區中的套件，並與專案的程式碼一起上傳。

在部署應用程式前，您可以搭配 -t DIRECTORY 標記使用 pip install 指令，將私人依附元件複製到本機目錄中，步驟如下：

  1. 將依附元件複製到本機目錄： 
    pip install -t DIRECTORY DEPENDENCY
  2. 在 DIRECTORY 目錄中新增一個空白的 __init__.py 檔案，將其轉換成模組。
  3. 從此模組匯入以使用您的依附元件： 
    import DIRECTORY.DEPENDENCY

預先安裝的套件

部署函式時，Python 建構包會安裝下列 Python 套件。如果您要在函式程式碼中使用下列任一套件，請在 requirements.txt 檔案中加入下列版本：

如要避免依附元件版本更新造成問題，請將套件固定在特定版本。

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

Python 建構套件會安裝下列套件，並固定為特定版本：

  • pip (最新版本)
  • setuptools (最新版本)
  • wheel (取決於產品需求)

Python 執行階段在執行環境中還包含多個系統套件。