設定環境變數 (第 1 代)

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

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

您可以使用 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...

如要將設定儲存在檔案中 (例如在來源控制項下)，可以搭配 --env-vars-file 標記使用 YAML 檔案：

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. 按一下「建立函式」。

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

4. 開啟「執行階段、建構作業和連線設定」專區。

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

6. 在「執行階段環境變數」部分中，按一下「新增變數」，然後新增名稱和值。

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

更新執行階段環境變數

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

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. 按一下 [編輯]。

4. 開啟「執行階段、建構作業和連線設定」專區。

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

6. 在「執行階段環境變數」部分進行編輯。

刪除執行階段環境變數

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. 按一下 [編輯]。

4. 開啟「執行階段、建構作業和連線設定」專區。

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

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 nodejs20 \
--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;
}

使用建構環境變數

您也可以為支援建構套件的執行階段設定建構環境變數。

建構環境變數是與函式一起部署的鍵/值組合，可讓您將設定資訊傳遞至建構套件。舉例來說，您可能想自訂編譯器選項。您可以使用 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. 按一下「建立函式」。

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

4. 開啟「執行階段、建構作業和連線設定」專區。

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

6. 在「建構環境變數」部分，按一下「新增變數」，然後新增名稱和值。

更新建構環境變數

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

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. 按一下 [編輯]。

4. 開啟「執行階段、建構作業和連線設定」專區。

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. 按一下 [編輯]。

4. 開啟「執行階段、建構作業和連線設定」專區。

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。

管理密鑰

環境變數可用於函式設定，但不建議用來儲存資料庫憑證或 API 金鑰等密鑰。這些較為敏感的值應儲存在原始碼和環境變數以外的位置。某些執行環境或架構可能會將環境變數的內容傳送至記錄檔，因此不建議將機密憑證儲存在 YAML 檔案、部署指令碼或來源控管系統中。

建議您使用 Secret Manager 儲存密鑰。如要設定 Cloud Run 函式來存取 Secret Manager 中儲存的密鑰，請參閱「設定密鑰」。 請注意，Cloud Run functions 沒有與 Cloud KMS 整合的專屬功能。

可攜性

目前適用於 Cloud Run 函式的環境變數，可能不適用於其他執行階段環境，例如使用不同語言，或搭配特定工具或程式庫。也可能無法在其他平台上使用。

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