設定環境變數 (第 1 代)

您可以連同 Cloud Run 函式一併部署任意鍵/值組合。這些組合會直接以環境變數形式提供給函式，供程式碼在執行階段存取，或做為 Google Cloud buildpack 的設定資訊。

環境變數會繫結至單一函式， Google Cloud 專案中的其他函式無法存取。每個變數都會儲存在 Cloud Run functions 後端，並與繫結的函式共用生命週期。

您可以使用 Google Cloud CLI 或 Google Cloud 控制台，新增或移除執行階段環境變數。

設定執行階段環境變數

以下方法可新建變數或完全取代現有變數。如要附加變更，請使用下一節所述的更新程序。

gcloud

如要使用 Google Cloud CLI 設定執行階段環境變數，請在部署時使用 --set-env-vars 旗標：

gcloud functions deploy --no-gen2 FUNCTION_NAME --set-env-vars FOO=bar FLAGS ...

您也可使用以半形逗號分隔的清單，設定多個執行階段環境變數：

gcloud functions deploy --no-gen2 FUNCTION_NAME --set-env-vars FOO=bar,BAZ=boo FLAGS...

如要將設定儲存在檔案中 (例如在原始碼控管區下)，可以使用 YAML 檔案搭配 --env-vars-file 旗標：

gcloud functions deploy --no-gen2 FUNCTION_NAME --env-vars-file .env.yaml FLAGS...

.env.yaml 檔案的內容如下：

 FOO: bar
 BAZ: boo

在以上範例中，FLAGS... 代表您在部署函式期間傳遞的其他選項。如需 deploy 指令的完整參考資料，請參閱 gcloud functions deploy。

Google Cloud 控制台 UI

函式建立期間，您可以在 Google Cloud 控制台設定執行階段環境變數：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 按一下「Create function」(建立函式)。

3. 填寫函式的必填欄位。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Runtime」(執行階段) 分頁標籤。

6. 在「Runtime environment variables」(執行階段環境變數) 部分，按一下「Add variable」(新增變數)，然後新增名稱和值。

   如要瞭解如何新增現有函式的環境變數，請參閱「更新執行階段環境變數」。

更新執行階段環境變數

您也可以更新現有函式的執行階段環境變數。這是非破壞性方法，可變更或新增執行階段環境變數，但不會刪除。

gcloud

如要使用 Google Cloud CLI 更新變數，請在部署時使用 --update-env-vars 旗標：

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-env-vars FOO=bar

您也可使用以半形逗號分隔的清單，更新多個執行階段環境變數：

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-env-vars FOO=bar,BAZ=boo

Google Cloud 控制台 UI

如要使用 Google Cloud 控制台更新執行階段環境變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 點選現有函式，前往對應的詳細資料頁面。

3. 按一下「Edit」(編輯)。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Runtime」(執行階段) 分頁標籤。

6. 在「Runtime environment variables」(執行階段環境變數) 部分編輯變數。

刪除執行階段環境變數

gcloud

如要移除特定的執行階段環境變數，可以在部署時使用 --remove-env-vars 旗標：

gcloud functions deploy FUNCTION_NAME --no-gen2 --remove-env-vars FOO,BAZ

您也可使用 --clear-env-vars 旗標，清除先前設定的所有執行階段環境變數：

gcloud functions deploy FUNCTION_NAME --no-gen2 --clear-env-vars

Google Cloud 控制台 UI

如要使用 Google Cloud 控制台刪除執行階段環境變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 點選現有函式，前往對應的詳細資料頁面。

3. 按一下「Edit」(編輯)。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Runtime」(執行階段) 分頁標籤。

6. 在「Runtime environment variables」(執行階段環境變數) 部分，按一下鍵/值組合旁的垃圾桶圖示，即可刪除組合。

自動設定執行階段環境變數

本節列出自動設定的執行階段環境變數。

鍵	說明
FUNCTION_TARGET	保留：要執行的函式。
FUNCTION_SIGNATURE_TYPE	保留：函式類型：HTTP 函式為 http，事件導向函式為 event。
K_SERVICE	保留：函式資源的名稱。
K_REVISION	保留：函式的版本 ID。
PORT	保留：函式叫用的通訊埠。

注意：如果函式需要舊版執行階段的環境變數，您可以在部署函式時設定。例如：

gcloud functions deploy envVarMemory \
--no-gen2 \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

設定及擷取執行階段環境變數的範例

設定執行階段環境變數：

Node.js

gcloud functions deploy envVar \
--runtime nodejs22 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 Node.js 支援版本的執行階段 ID，執行函式。

Python

gcloud functions deploy env_vars \
--runtime python312 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 Python 支援版本的執行階段 ID，執行函式。

Go

gcloud functions deploy EnvVar \
--runtime go121 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 Go 支援版本的執行階段 ID，執行函式。

Java

gcloud functions deploy java-envVar-function \
--entry-point functions.EnvVars \
--runtime java17 \
--memory 512MB \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 Java 支援版本的執行階段 ID，執行函式。

C#

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet6 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 .NET 支援版本的執行階段 ID，執行函式。

Ruby

gcloud functions deploy env_vars --runtime ruby33 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 Ruby 支援版本的執行階段 ID，執行函式。

PHP

 gcloud functions deploy envVar --runtime php82 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 旗標指定 PHP 支援版本的執行階段 ID，執行函式。

在執行階段以程式輔助存取變數：

Node.js

在 Node.js 中，使用 process.env 屬性存取執行階段環境變數：

exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

在 Python 中，使用 os.environ 存取執行階段環境變數：

import os


def env_vars(request):
    return os.environ.get("FOO", "Specified environment variable is not set.")

Go

在 Go 中，使用 os.Getenv() 存取執行階段環境變數：

// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"fmt"
	"net/http"
	"os"
)

// EnvVar is an example of getting an environment variable in a Go function.
func EnvVar(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "FOO: %q", os.Getenv("FOO"))
}

Java

在 Java 中，使用 System.getenv 存取執行階段環境變數：

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class EnvVars implements HttpFunction {

  // Returns the environment variable "foo" set during function deployment.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    String foo = System.getenv("FOO");
    if (foo == null) {
      foo = "Specified environment variable is not set.";
    }
    writer.write(foo);
  }
}

C#

在執行階段，可使用 C# 中的 Environment.GetEnvironmentVariable 存取環境變數：

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System;
using System.Threading.Tasks;

namespace EnvironmentVariables;

public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        string foo = Environment.GetEnvironmentVariable("FOO")
            ?? "Specified environment variable is not set.";
        await context.Response.WriteAsync(foo, context.RequestAborted);
    }
}

Ruby

在執行階段，可使用 Ruby 中的 ENV 存取環境變數：

require "functions_framework"

FunctionsFramework.http "env_vars" do |_request|
  ENV["FOO"] || "Specified environment variable is not set."
end

PHP

在執行階段，可使用 PHP 的 getenv 函式存取環境變數：

use Psr\Http\Message\ServerRequestInterface;

function envVar(ServerRequestInterface $request): string
{
    return getenv('FOO') . PHP_EOL;
}

使用建構環境變數

如果執行階段支援 buildpack，您也可以設定建構環境變數。

建構環境變數是與函式一併部署的鍵/值組合，可將設定資訊傳遞至 buildpack。舉例來說，如果您想自訂編譯器選項，就可以使用 Google Cloud CLI 或 Google Cloud 控制台 UI，新增或移除這些建構環境變數。

注意：鍵的開頭須為大寫 ASCII 字母，且只能包含大寫 ASCII 字母、數字和底線。請避免建立開頭為 GOOGLE_* 前置字元的變數鍵。查看所有支援的 buildpack 環境變數。

設定建構環境變數

以下方法可新建變數或完全取代現有變數。如要附加變更，請使用下一節所述的更新程序 (gcloud 中的 --update-build-env-vars 旗標)。

gcloud

如要使用 Google Cloud CLI 設定變數，請在部署時使用 --set-build-env-vars 旗標：

gcloud beta functions deploy FUNCTION_NAME --no-gen2 --set-build-env-vars FOO=bar FLAGS...

您也可使用以半形逗號分隔的清單，設定多個建構環境變數：

gcloud functions deploy FUNCTION_NAME --no-gen2 --set-build-env-vars FOO=bar,BAZ=boo FLAGS...

如要將設定儲存在檔案中 (例如在原始碼控管區下)，可以使用 YAML 檔案搭配 --build-env-vars-file 旗標：

gcloud functions deploy FUNCTION_NAME --no-gen2 --build-env-vars-file FILE_NAME.yaml FLAGS...

*.yaml 檔案的內容如下：

 FOO: bar
 BAZ: boo

在以上範例中，FLAGS... 代表您在部署函式期間傳遞的其他選項。如需 deploy 指令的完整參考資料，請參閱 gcloud beta functions deploy。

Google Cloud 控制台 UI

函式建立期間，您也可以在 Google Cloud 控制台設定建構環境變數：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 按一下「Create function」(建立函式)。

3. 填寫函式的必填欄位。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Build」(建構) 分頁標籤。

6. 在「Build environment variables」(建構環境變數) 部分，按一下「Add variable」(新增變數)，然後新增名稱和值。

更新建構環境變數

您也可以更新現有函式的建構環境變數。這是非破壞性方法，可變更或新增建構環境變數，但不會刪除。

gcloud

如要使用 Google Cloud CLI 設定變數，請在部署時使用 --update-build-env-vars 旗標：

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-build-env-vars FOO=bar

您也可使用以半形逗號分隔的清單，更新多個建構環境變數：

gcloud functions deploy FUNCTION_NAME --no-gen2 --update-build-env-vars FOO=bar,BAZ=boo

Google Cloud 控制台 UI

如要使用 Google Cloud 控制台更新建構環境變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 點選現有函式，前往對應的詳細資料頁面。

3. 按一下「Edit」(編輯)。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Build」(建構) 分頁標籤。

6. 在「Build environment variables」(建構環境變數) 部分編輯變數。

刪除建構環境變數

gcloud

如要移除特定的建構環境變數，可以在部署時使用 --remove-build-env-vars 旗標：

gcloud functions deploy FUNCTION_NAME --no-gen2 --remove-build-env-vars FOO,BAZ

或者，也可以使用 --clear-build-env-vars 旗標，清除先前設定的所有建構環境變數：

gcloud functions deploy FUNCTION_NAME --no-gen2 --clear-build-env-vars

Google Cloud 控制台 UI

如要使用 Google Cloud 控制台刪除建構環境變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台開啟「Functions Overview」(函式總覽) 頁面：

   前往「Cloud Run functions Overview」(Cloud Run 函式總覽) 頁面

2. 點選現有函式，前往對應的詳細資料頁面。

3. 按一下「Edit」(編輯)。

4. 開啟「Runtime, build and connections settings」(執行階段、建構和連線設定) 部分。

5. 選取「Build」(建構) 分頁標籤。

6. 在「Build environment variables」(建構環境變數) 部分，按一下鍵/值組合旁的垃圾桶圖示，即可刪除組合。

變數生命週期

所有環境變數都會繫結至 Cloud Run 函式的部署作業，也只能隨部署作業設定或變更。如果部署作業因任何原因失敗，所有環境變數異動均「不會」套用。部署作業必須成功，環境變數才會變更。

最佳做法和保留的環境變數

根據函式使用的執行階段，系統會自動設定一些額外的環境變數，具體取決於執行階段的作業系統 (例如 DEBIAN_FRONTEND、SHLVL 或 PATH)，以及語言執行階段 (例如 NODE_ENV、VIRTUAL_ENV 或 GOPATH)。

在日後的執行階段版本中，環境提供的環境變數可能會變更 (「自動設定的環境變數」所列載的變數除外)。建議的最佳做法是，不要依賴或修改您未明確設定的任何環境變數。

若修改環境提供的環境變數，或許會導致無法預測的結果。嘗試修改這類環境變數時，可能會遭到封鎖，或是函式無法啟動等非預期的後果。最佳做法是對所有環境變數加上不重複的鍵做為前置字元，避免發生衝突。

最後，您無法使用下列環境變數：

鍵	說明
空白 ('')	鍵不得為空字串。
=	鍵不得包含「=」字元。
X_GOOGLE_	鍵不得包含前置字元 X_GOOGLE_。

注意：若環境變數在執行環境中顯示，但未記錄於上表，應視為已淘汰，且隨時可能消失，不會另行通知。

大小限制

個別函式的執行階段環境變數名稱與值，所使用的位元組總數上限為 32 KiB。個別鍵或值則沒有特定容量限制，只要總額不超過上限即可。

最多可定義 100 個建構環境變數，定義字串 foo=bar 的大小上限為 64 KiB。

管理 Secret

環境變數可用於函式設定，但不建議用來儲存資料庫憑證或 API 金鑰等 Secret。這些值較為機密，應儲存在原始碼與環境變數以外的地方。部分執行環境或所用架構可能會將環境變數內容傳送至記錄檔，因此最好不要將機密憑證儲存在 YAML 檔案、部署指令碼或原始碼控管區。

建議您使用 Secret Manager 儲存 Secret。如要設定 Cloud Run functions，存取儲存在 Secret Manager 中的 Secret，請參閱「設定 Secret」。請注意，Cloud Run functions 並未與 Cloud KMS 整合。

可攜權

目前適用於 Cloud Run 函式的環境變數，可能不適用於其他執行階段環境，例如不同語言，或是特定工具或程式庫的執行階段。其他平台也可能不接受這些變數。

您可以遵循環境變數的 POSIX 標準，避免這類問題。如果您使用 Google Cloud 控制台編輯變數，當定義的變數可能有可攜權問題時，Google Cloud 控制台會發出警告 (但不會阻止部署作業)。一般而言，我們建議環境變數鍵只包含大寫英文字母、數字和 <underscore> (_)，如「可攜字元集」所定義，且不得以數字開頭。