建構 Python 應用程式

建構套件支援透過環境變數進行語言慣用設定。

指定 Python 版本

根據預設，Python 執行階段建構套件會使用最新穩定版的 Python 解譯器。如果應用程式需要特定版本，您可以在應用程式的根目錄中加入 .python-version 檔案，指定所需版本。

3.13

使用GOOGLE_PYTHON_VERSION

您也可以透過 GOOGLE_PYTHON_VERSION 環境變數指定 Python 版本。如果同時設定這兩項，GOOGLE_PYTHON_VERSION 值會優先於 .python-version 檔案。根據預設，如果未指定 .python-version 檔案和 GOOGLE_PYTHON_VERSION 環境變數，系統會使用最新 LTS 版本的 Python。

如要設定建構套件，在部署應用程式時使用 Python 3.13，請按照下列步驟操作：

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

您也可以使用 project.toml 專案描述元，在專案檔案旁編碼環境變數。請參閱使用環境變數建構應用程式的說明。

使用 pip 指定依附元件

Python buildpack 支援使用 pip 管理應用程式依附元件。應用程式依附元件應在根目錄的 requirements.txt 檔案中宣告。

requirements.txt 檔案中，一行代表一個套件，每行都包含套件名稱，並可視需要加入要求的版本。詳情請參閱 requirements.txt 參考資料。

以下是 requirements.txt 檔案範例：

requests==2.20.0
numpy

設定 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 建構套件會自動為 Cloud Build 服務帳戶產生 Artifact Registry 憑證。您只需在 requirements.txt 中加入 Artifact Registry 網址，不必產生額外憑證。例如：

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

應用程式進入點

下節說明 Python 建構包的預設進入點。

Cloud Run 來源部署作業的進入點

只有在將原始碼部署至 Cloud Run 時使用 Python 執行階段，才能使用這項功能。如果您直接使用 pack build 建構容器映像檔，而非透過 Cloud Run 來源部署程序，則不適用這項功能。

Python 建構包支援 FastAPI、Gradio 和 Streamlit 等現代網路架構。

Python 3.12 以下版本

如果您使用 Python 3.12 以下版本，Python 建構套件預設會使用 Gunicorn 做為工作負載的 WSGI HTTP 伺服器。Python 建構套件會將預設進入點設為 gunicorn -b :8080 main:app。

Python 3.13 以上版本

如果是 Python 3.13 以上版本，Python 建構套件會根據 requirements.txt 檔案中的網路伺服器或架構設定，為 Cloud Run 來源部署作業設定預設進入點。這項預設設定僅適用於 Cloud Run 服務來源部署作業，不適用於 Cloud Run 函式。

使用 Python 執行階段從來源部署 Cloud Run 服務時，建構包會透過下列方式判斷 Python 版本和預設進入點：

  • 如果您未在來源檔案中指定 Python 版本，Python 建構套件會將預設版本設為最新支援的 Python 版本。建構包會根據您在 requirements.txt 檔案中設定的網路伺服器或架構，決定預設進入點。

  • 如果您未在 requirements.txt 檔案中指定網路伺服器或架構，Python 建構包預設會使用 Gunicorn 做為工作負載的 WSGI HTTP 伺服器。Python 建構套件會將預設進入點設為 gunicorn -b :8080 main:app。

  • Python 建構套件會根據 requirements.txt 檔案中定義的下列優先順序，設定預設進入點：

    1. gunicorn
    2. uvicorn
    3. gradio
    4. streamlit。

設定網路伺服器或架構

下表列出從來源部署至 Cloud Run 時，requirements.txt 檔案中各項常見 Python 設定的預設進入點：

主要設定 預設進入點 環境變數
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 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 檔案中指定網路伺服器。

或者，您也可以執行下列來源部署指令來指定進入點：

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

更改下列內容：

  • SERVICE：要部署的服務名稱。
  • ENTRYPOINT：您要用於原始碼的預設進入點。

如果無法將原始碼部署至 Cloud Run，或在記錄中發現錯誤，請參閱 Cloud Run 疑難排解指南。

所有其他部署作業的進入點

Python 建構套件會使用 Gunicorn 做為工作負載的預設 WSGI HTTP 伺服器。使用 Python 建構套件建構的應用程式會以預設設定啟動 gunicorn 程序，類似於執行：

gunicorn --bind :8080 main:app

自訂應用程式進入點

您可以使用 Procfile 或環境變數，自訂應用程式啟動指令。您可能需要這麼做，才能自訂預設進入點設定。

您可以在根目錄中建立 Procfile，並使用自訂設定。 範例：

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

或者，您也可以使用 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。