设置构建环境变量（源代码部署）

构建环境变量是键值对，可让您在从源代码进行部署时将配置信息传递给 Buildpack。例如，在构建时，您可能想要自定义编译器选项、指定构建时证书、配置参数，等等。

本页面介绍了如何设置构建时可用的构建环境变量，适用于从源代码部署 Cloud Run 服务或函数的平台开发者。源代码部署 (--source) 支持构建环境变量 gcloud CLI 标志，容器映像部署 (--image) 则不支持。

您可以使用环境变量进行服务或函数配置，但我们不建议您将其用作存储数据库凭证或 API 密钥等 Secret 的方式。请将敏感值存储在源代码和环境变量以外的位置。为了安全地存储 Secret，我们建议使用 Secret Manager。如需配置访问 Secret Manager 中存储的 Secret 的服务，请参阅配置 Secret。

准备工作

• 启用 Cloud Run Admin API 和 Cloud Build API：

  gcloud services enable run.googleapis.com \
      cloudbuild.googleapis.com

  启用 Cloud Run Admin API 后，系统会自动创建 Compute Engine 默认服务账号。

所需的角色

您或您的管理员必须为部署者账号和 Cloud Build 服务账号授予以下 IAM 角色。

点击可查看部署者账号所需的角色

如需获得从来源进行构建和部署所需的权限，请让管理员向您授予以下 IAM 角色：

• 针对项目的 Cloud Run Source Developer (roles/run.sourceDeveloper)
• 针对项目的 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• 针对 Cloud Run 服务身份的 Service Account User (roles/iam.serviceAccountUser)

点击可查看 Cloud Build 服务账号需要的角色

除非您替换此行为，否则 Cloud Build 会自动使用 Compute Engine 默认服务账号作为默认 Cloud Build 服务账号来构建源代码和 Cloud Run 资源。为了让 Cloud Build 能够构建来源，请让管理员向项目的 Compute Engine 默认服务账号授予 Cloud Run Builder (roles/run.builder)：

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:[e-mail] \
      --role=roles/run.builder
  

将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号，将 PROJECT_ID 替换为您的 Google Cloud项目 ID。如需详细了解如何查找项目 ID 和项目编号，请参阅创建和管理项目。

向 Compute Engine 默认服务账号授予 Cloud Run Builder 角色需要几分钟时间才能传播。

注意：

iam.automaticIamGrantsForDefaultServiceAccounts 组织政策限制条件可以防止将 Editor 角色自动授予默认服务账号。如果您的组织是在 2024 年 5 月 3 日之后创建的，则默认情况下会强制执行此限制条件。

我们强烈建议您实施此限制条件，以停用自动角色授予功能。如果您停用自动角色授予功能，则必须决定向默认服务账号授予哪些角色，然后自行授予这些角色。

如果默认服务账号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。如需安全地修改服务账号的角色，请使用 Policy Simulator 查看更改的影响，然后授予和撤消相应的角色。

如需查看与 Cloud Run 关联的 IAM 角色和权限的列表，请参阅 Cloud Run IAM 角色和 Cloud Run IAM 权限。如果您的 Cloud Run 服务与Google Cloud API（例如 Cloud 客户端库）进行交互，请参阅服务身份配置指南。如需详细了解如何授予角色，请参阅部署权限和管理访问权限。

构建环境变量数量上限和限制

您最多可以定义 100 个构建环境变量，键和值的总大小限制为 64 KiB。

设置构建环境变量

您可以设置构建环境变量以建立新变量或完全替换现有构建变量。

注意：键必须以大写的 ASCII 字母开头，并且包含大写的 ASCII 字母、数字和下划线。您应该避免创建前缀为 GOOGLE_* 的变量键。查看所有受支持的 Buildpack 环境变量。

gcloud

如需在从源代码部署服务时设置构建环境变量，请使用 --set-build-env-vars 标志：

gcloud run deploy SERVICE \
    --source . \
    --set-build-env-vars KEY1=VALUE1,KEY2=VALUE2

您需要进行如下替换：

• 将 SERVICE 替换为您的 Cloud Run 服务的名称。
• 将 KEY1=VALUE1,KEY2=VALUE2 替换为与允许您将配置信息传递给 Buildpack 的函数一起部署的变量名称及其值的逗号分隔列表。

如果您要部署函数，请将 --function 标志与源代码中的函数入口点一起添加。

更新构建环境变量

您可以更新现有服务的构建环境变量。这种方法没有破坏性，也就是说，它只会更改或添加构建环境变量，但不会删除构建环境变量。

gcloud

如需更新现有服务的构建环境变量，请使用 --update-build-env-vars 标志：

gcloud run deploy SERVICE \
    --source . \
    --update-build-env-vars KEY1=VALUE1,KEY2=VALUE2

如果您要部署函数，请将 --function 标志与源代码中的函数入口点一起添加。

删除构建环境变量

您可以删除现有服务的构建环境变量。

gcloud

如需移除现有服务的构建环境变量，请使用 --remove-build-env-vars 标志：

gcloud run deploy SERVICE \
    --source . \
    --remove-build-env-vars KEY1=VALUE1,KEY2=VALUE2

或者，您也可以为现有函数使用 --clear-build-env-vars 来清除构建环境变量：

gcloud run deploy SERVICE \
    --source . \
    --clear-build-env-vars KEY1=VALUE1,KEY2=VALUE2

如果您要部署函数，请将 --function 标志与源代码中的函数入口点一起添加。

使用构建环境变量文件

您可以将构建环境变量文件用于现有函数。

gcloud

如需通过文件设置构建环境变量，请使用 --build-env-vars-file 标志：

gcloud run deploy SERVICE \
    --source . \
    --build-env-vars-file FILE_NAME.yaml

替换 FILE_NAME.yaml，文件的内容应如下所示：

 KEY1: VALUE1
 KEY2: VALUE2

如果您要部署函数，请将 --function 标志与源代码中的函数入口点一起添加。