配置环境变量（第 1 代）

您可以将任意键值对与 Cloud Run 函数一起部署。这些对可以作为字面量环境变量供您的函数使用（可以在运行时由您的代码访问），也可以作为 Google Cloud Buildpack 的配置信息。

环境变量绑定到单个函数，对您 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...

如果您想将配置存储在一个文件中（例如，存储在源代码控制系统下），可以将 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 控制台界面

您可以在创建函数时使用 Google Cloud 控制台设置运行时环境变量：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

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 控制台界面

如需使用 Google Cloud 控制台更新运行时环境变量，请执行以下操作：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

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 控制台界面

如需使用 Google Cloud 控制台删除运行时环境变量，请执行以下操作：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

2. 点击现有函数以转至其详情页面。

3. 点击修改。

4. 打开运行时、构建和连接设置部分。

5. 选择运行时标签页。

6. 在运行时环境变量部分中，点击键值对旁边的垃圾图标以将其删除。

自动设置的运行时环境变量

本部分列出了自动设置的运行时环境变量。

键	说明
FUNCTION_TARGET	预留：要执行的函数。
FUNCTION_SIGNATURE_TYPE	预留：函数的类型（HTTP 函数类型为 http，事件驱动的函数类型为 event）。
K_SERVICE	预留：函数资源的名称。
K_REVISION	预留：函数的版本标识符。
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 go122 \
--set-env-vars FOO=bar \
--trigger-http

使用 --runtime 标志可以指定支持的 Go 版本的运行时 ID 来运行您的函数。

Java

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

使用 --runtime 标志可以指定支持的 Java 版本的运行时 ID 来运行您的函数。

C#

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet8 \
--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 php83 \
--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 控制台界面添加或移除这些构建环境变量。

注意：键必须以大写的 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 控制台界面

您还可以在创建函数期间使用 Google Cloud 控制台来设置构建环境变量：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

2. 点击创建函数。

3. 填写函数的必填字段。

4. 打开运行时、构建和连接设置部分。

5. 选择构建标签页。

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 控制台界面

如需使用 Google Cloud 控制台更新构建环境变量，请执行以下操作：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

2. 点击现有函数以转至其详情页面。

3. 点击修改。

4. 打开运行时、构建和连接设置部分。

5. 选择构建标签页。

6. 在构建环境变量部分中进行修改。

删除构建环境变量

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 控制台界面

如需使用 Google Cloud 控制台删除构建环境变量，请执行以下操作：

1. 在 Google Cloud 控制台中打开 Functions 概览页面：

   前往 Cloud Run functions 概览页面。

2. 点击现有函数以转至其详情页面。

3. 点击修改。

4. 打开运行时、构建和连接设置部分。

5. 选择构建标签页。

6. 在构建环境变量部分中，点击键值对旁边的垃圾图标以将其删除。

变量生命周期

所有环境变量是在部署 Cloud Run functions 函数时绑定的，并且只能通过部署进行设置或更改。如果部署因任何原因失败，对环境变量进行的任何更改都不会应用。要更改环境变量，部署必须取得成功。

最佳做法和预留的环境变量

其他一些环境变量是根据您的函数使用的运行时自动设置的。这些环境变量基于运行时的操作系统（例如 DEBIAN_FRONTEND、SHLVL 或 PATH）以及语言运行时（例如 NODE_ENV、VIRTUAL_ENV 或 GOPATH）。

环境提供的环境变量（自动设置的环境变量中列出的环境变量除外）可能会在后续运行时版本中发生变化。我们建议的最佳做法是，不要依赖或修改任何未明确设置的环境变量。

修改环境提供的环境变量可能会导致不可预知的结果。尝试修改此类环境变量的行为可能被系统阻止，导致意外的后果（例如函数无法启动）。最佳做法是考虑为所有环境变量添加一个唯一键作为前缀，以避免冲突。

最后，您不能使用以下环境变量：

键	说明
空 ('')	键不能是空字符串。
=	键不能包含“=”字符。
X_GOOGLE_	键不能包含 X_GOOGLE_ 前缀。

注意：如果有环境变量显示在执行环境中，但并未记录在上表中，则应将其视为已弃用，并且我们可能随时不经通知将其删除。

大小限制

单个函数的环境变量名称和值使用的字节总数限制为 32KiB。在此整体容量内，对单个键或值没有具体限制。

对于构建环境变量，最多可以定义 100 个变量，定义字符串 foo=bar 仅限 64KiB。

管理密文

环境变量可用于配置函数，但建议不要使用其来存储密钥（例如数据库凭据或 API 密钥）。 这些更敏感的值应存储在源代码和外部环境变量以外的位置。某些执行环境或某些框架的使用可能会导致环境变量的内容被发送到日志，因此建议不要将敏感凭据存储在 YAML 文件或部署脚本中，也不要将其存储在源代码控制系统下。

如需存储 Secret，我们建议您使用 Secret Manager。如需配置 Cloud Run functions 以访问 Secret Manager 中存储的 Secret，请参阅配置 Secret。请注意，Cloud Run functions 函数与 Cloud KMS 之间不存在任何特定的集成。

可移植性

当前适用于您的 Cloud Run 函数的环境变量有可能不适用于其他运行时环境，例如不同的语言或者特定的工具或库。另外，其他平台可能不支持这些环境变量。

为避免出现此类问题，您可以按照 POSIX 环境变量标准中的说明操作。 如果您使用 Google Cloud 控制台修改变量，则当定义的变量可能存在可移植性问题时，Google Cloud 控制台会向您发出警告（但不会阻止部署）。一般来说，我们建议环境变量键仅包含大写字母、数字和 <underscore> (_)（如可移植的字符集中所述），并且不要以数字开头。