在构建配置文件中使用 substitutions 以在构建时替代特定变量。
对于那些直到构建时才知道值的变量，或者使用不同的变量值重用现有构建请求，替代变量很有用。
Cloud Build 提供内置替代变量，您也可以定义自己的替代变量。在构建的 steps 和 images 中使用 substitutions 可在构建时解析它们的值。
本页面介绍了如何使用默认替代变量或者定义自己的 substitutions。
使用默认替代变量
Cloud Build 为所有构建提供以下默认替代变量：
$PROJECT_ID：您的 Cloud 项目的 ID$BUILD_ID：您的构建的 ID$PROJECT_NUMBER：您的项目编号$LOCATION：与构建关联的区域
Cloud Build 为触发器调用的构建提供以下默认替代变量：
$TRIGGER_NAME：与触发器关联的名称$COMMIT_SHA：与您的构建关联的提交 ID$REVISION_ID：与您的构建关联的提交 ID$SHORT_SHA：COMMIT_SHA的前七个字符$REPO_NAME：代码库的名称$REPO_FULL_NAME：代码库的全名，包括用户或组织$BRANCH_NAME：您的分支名称$TAG_NAME：您的标记名称$REF_NAME：分支或标记的名称$TRIGGER_BUILD_CONFIG_PATH：构建执行期间使用的构建配置文件的路径；否则，如果构建是在触发器上以内嵌方式配置的，或构建使用Dockerfile或Buildpack，则为空字符串。$SERVICE_ACCOUNT_EMAIL：您用于 build 的服务账号的电子邮件地址。这可以是默认服务账号，也可以是用户指定的服务账号。$SERVICE_ACCOUNT：服务账号的资源名称，格式为projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build 提供以下特定于 GitHub 的默认替代变量，用于拉取请求触发器：
$_HEAD_BRANCH：拉取请求的标头分支$_BASE_BRANCH：拉入请求的基本分支$_HEAD_REPO_URL：拉取请求的标头代码库网址$_PR_NUMBER：拉取请求编号
如果默认替代变量不可用（例如无源构建或使用存储源的构建），则会使用空字符串替换出现的缺失变量。
使用 gcloud builds submit 启动构建时，您可以使用 --substitutions 参数指定通常来自触发构建的变量。具体来说，您可以手动提供以下变量的值：
$TRIGGER_NAME$COMMIT_SHA$REVISION_ID$SHORT_SHA$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$REF_NAME$TRIGGER_BUILD_CONFIG_PATH$SERVICE_ACCOUNT_EMAIL$SERVICE_ACCOUNT
例如，以下命令使用 TAG_NAME 替代变量：
gcloud builds submit --config=cloudbuild.yaml \ --substitutions=TAG_NAME="test" 以下示例使用默认替代变量 $BUILD_ID、$PROJECT_ID、$PROJECT_NUMBER 和 $REVISION_ID。
YAML
steps: # Uses the ubuntu build step: # to run a shell script; and # set env variables for its execution - name: 'ubuntu' args: ['bash', './myscript.sh'] env: - 'BUILD=$BUILD_ID' - 'PROJECT_ID=$PROJECT_ID' - 'PROJECT_NUMBER=$PROJECT_NUMBER' - 'REV=$REVISION_ID' # Uses the docker build step to build an image called my-image - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.'] # my-image is pushed to Container Registry images: - 'gcr.io/$PROJECT_ID/my-image' JSON
{ "steps": [{ "name": "ubuntu", "args": [ "bash", "./myscript.sh" ], "env": [ "BUILD=$BUILD_ID", "PROJECT_ID=$PROJECT_ID", "PROJECT_NUMBER=$PROJECT_NUMBER", "REV=$REVISION_ID" ] }, { "name": "gcr.io/cloud-builders/docker", "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."] }], "images": [ "gcr.io/$PROJECT_ID/my-image" ] } 以下示例演示了使用 docker 构建步骤构建映像的构建请求，然后使用默认的 $PROJECT_ID 替代变量将映像推送到 Container Registry：
在此示例中：
- 构建请求包含一个构建步骤，在
gcr.io/cloud-builders中使用docker构建步骤来构建 Docker 映像。- 该步骤中的
args字段指定传递给docker命令的参数，在此示例中，系统将调用build -t gcr.io/my-project/cb-demo-img .（使用您的项目 ID 替换$PROJECT_ID后）。
- 该步骤中的
images字段包含映像的名称。如果构建成功，则生成的映像将推送到 Container Registry。如果构建未成功创建映像，则构建将失败。
YAML
steps: - name: gcr.io/cloud-builders/docker args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."] images: - gcr.io/$PROJECT_ID/cb-demo-img JSON
{ "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."] }], "images": [ "gcr.io/$PROJECT_ID/cb-demo-img" ] } 使用用户定义的替代变量
您也可以定义自己的替代变量。用户定义的替代变量必须遵循以下规则：
- 替代变量必须以下划线 (
_) 开头，并且只能使用大写字母和数字（遵循正则表达式格式_[A-Z0-9_]+）。这样做可以防止与内置替代变量产生冲突。如需使用以$开头的表达式，您必须使用$$. Thus:$FOOis invalid since it is not a built-in substitution.$$FOO，其计算结果为字面量字符串$FOO。
- 参数数量的上限为 200 个。参数键的长度上限为 100 个字节，参数值的长度上限为 4000 个字节。
$_FOO和${_FOO}计算结果均为_FOO的值。但是，${}允许替代变量在两侧都没有空格的情况下也能够起作用，这意味着允许使用${_FOO}BAR等替代变量。$$allows you to include a literal$in the template. Thus:$_FOOevaluates to the value of_FOO.$$_FOO计算结果为文字字符串$_FOO。$$$_FOO计算结果为文字字符串$，后跟_FOO的值。
如需使用替代变量，请在
gcloud命令中使用--substitutions参数，或在配置文件中指定替代变量。以下示例演示了一个构建配置，其中包含两个用户定义的替代变量，分别名为
_NODE_VERSION_1和_NODE_VERSION_2：YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '--build-arg', 'node_version=${_NODE_VERSION_1}', '-t', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}', '.'] - name: 'gcr.io/cloud-builders/docker' args: ['build', '--build-arg', 'node_version=${_NODE_VERSION_2}', '-t', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}', '.'] substitutions: _NODE_VERSION_1: v6.9.1 # default value _NODE_VERSION_2: v6.9.2 # default value images: [ 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}', 'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}' ]JSON
{ "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": [ "build", "--build-arg", "node_version=${_NODE_VERSION_1}", "-t", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}", "." ] }, { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "--build-arg", "node_version=${_NODE_VERSION_2}", "-t", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}", "." ] }], "substitutions": { "_NODE_VERSION_1": "v6.9.1" "_NODE_VERSION_1": "v6.9.2" }, "images": [ "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}", "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}" ] }如需覆盖您在编译配置文件中指定的替换值，请在
gcloud builds submit命令中使用--substitutions标记。请注意，替代变量是变量到值的映射，而不是数组或序列。您可以替换$PROJECT_ID和$BUILD_ID之外的默认替代变量值。以下命令会替换上面的构建配置文件中指定的_NODE_VERSION_1的默认值：gcloud builds submit --config=cloudbuild.yaml \ --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .默认情况下，如果缺少替代变量或缺少替换，则构建将返回错误。但是，您可以设置
ALLOW_LOOSE选项以跳过此检查。以下代码段打印“hello world”并定义未使用的替换。 由于设置了
ALLOW_LOOSE替换选项，因此即使缺少替代变量，构建也会成功。YAML
steps: - name: 'ubuntu' args: ['echo', 'hello world'] substitutions: _SUB_VALUE: unused options: substitutionOption: 'ALLOW_LOOSE'JSON
{ "steps": [ { "name": "ubuntu", "args": [ "echo", "hello world" ] } ], "substitutions": { "_SUB_VALUE": "unused" }, "options": { "substitution_option": "ALLOW_LOOSE" } }如果由触发器调用您的构建，则默认情况下会设置
ALLOW_LOOSE选项。在这种情况下，如果存在缺失的替换变量或缺失的替换，则构建不会返回错误。对于由触发器调用的构建，您无法替换ALLOW_LOOSE选项。如果未指定
ALLOW_LOOSE选项，则替代变量映射或构建请求中的不匹配键会产生错误。例如，当构建请求包含$_FOO且替代变量映射未定义_FOO时，如果您的触发器包含替代变量，则在运行构建或调用触发器后，您将收到错误。即使您未设置
ALLOW_LOOSE选项，以下替代变量也始终包含默认的空字符串值：$REPO_NAME$REPO_FULL_NAME$BRANCH_NAME$TAG_NAME$COMMIT_SHA$SHORT_SHA
定义替代变量时，您并非只能使用静态字符串。您还可以访问调用触发器的事件载荷。这些载荷可作为载荷绑定使用。您还可以对替代变量应用 bash 参数扩展，并将生成的字符串存储为新的替代变量。如需了解详情，请参阅在替代中使用载荷绑定和 bash 参数扩展。
动态替代
您可以通过将构建配置文件中的
dynamicSubstitutions选项设置为true来引用用户定义的替代变量中另一个变量的值。如果由触发器调用您的构建，则dynamicSubstitutions字段始终设置为true，无需在构建配置文件中指定。如果是手动调用您的构建，则必须将dynamicSubstitutions字段设置为true，以便在运行构建时解读 bash 参数扩展。以下构建配置文件显示了引用变量
${PROJECT_ID}的替代变量${_IMAGE_NAME}。dynamicSubstitutions字段设置为true，因此将在手动调用构建时应用引用：YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', '${_IMAGE_NAME}', '.'] substitutions: _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image' options: dynamicSubstitutions: trueJSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "${_IMAGE_NAME}", "." ] } ], "substitutions": { "_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image" }, "options": { "dynamic_substitutions": true } }如需了解详情，请参阅应用 bash 参数扩展。
将替换项映射到环境变量
脚本不直接支持替换，但支持环境变量。您可以将替换项映射到环境变量，方法是一次性自动映射，也可以手动映射（即自行定义每个环境变量）。
自动映射替换项
在 build 级别。如需自动将所有替换项映射到将在整个 build 中可用的环境变量，请在 build 级别将
automapSubstitutions设置为true作为选项。例如，以下 build 配置文件显示了映射到环境变量的用户定义替换项$_USER和默认替换项$PROJECT_ID：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'" } ], "options": { "automap_substitutions": true }, "substitutions": { "_USER": "Google Cloud" } }在步骤级别。如需在单个步骤中自动映射所有替换项并将其作为环境变量提供，请在此步骤中将
automapSubstitutions字段设置为true。在以下示例中，只有第二步会正确显示替换项，因为它是唯一启用了自动替换项映射的步骤：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": true } ], }, "substitutions": { "_USER": "Google Cloud" }此外，您还可以将替换项作为环境变量在整个 build 中提供，然后在一步中忽略它们。在构建级别将
automapSubstitutions设置为true，然后在您要忽略替换项的步骤中将同一字段设置为false。在以下示例中，即使在 build 级别启用了映射替换，系统也不会在第二步中输出项目 ID，因为automapSubstitutions在此步骤中设置为false：YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: false options: automapSubstitutions: true substitutions: _USER: "Google Cloud"JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": false } ], "options": { "automap_substitutions": true }, }, "substitutions": { "_USER": "Google Cloud" }
手动映射替换项
您可以手动将替换项映射到环境变量。每个环境变量都是使用
env字段在步骤级别定义的，并且变量的范围仅限于其定义的步骤。此字段接受键值对的列表。以下示例展示了如何将替换项
$PROJECT_ID映射到环境变量BAR：YAML
steps: - name: 'ubuntu' env: - 'BAR=$PROJECT_ID' script: 'echo $BAR'JSON
{ "steps": [ { "name": "ubuntu", "env": [ "BAR=$PROJECT_ID" ], "script": "echo $BAR" } ] }后续步骤
- 了解如何在替代变量中使用载荷绑定和 bash 参数扩展。
- 了解如何创建基本构建配置文件。
- 了解如何创建和管理构建触发器。
- 了解如何在 Cloud Build 中手动运行构建。
您可以使用以下两种方式之一来指定变量：$_FOO 或 ${_FOO}：