Google Cloud Build替换变量报错：FIREBASE_API_KEY非内置替换项

一、解决构建报错：invalid value for 'build.substitutions': key in the template "FIREBASE_API_KEY" is not a valid built-in substitution #

这个报错的核心原因是Cloud Build的自定义替换变量必须以_开头，你大概率是在Cloud Build触发器的替换变量设置中，使用了不带下划线的变量名（比如FIREBASE_API_KEY），而非yaml中定义的_FIREBASE_API_KEY。Cloud Build会将不带下划线的变量识别为内置系统变量，但FIREBASE_API_KEY并非内置变量，因此触发报错。

修复步骤： #

1. 打开Google Cloud控制台的Cloud Build触发器页面，找到你的构建触发器
2. 进入触发器的「编辑」页面，找到「替换变量」区域
3. 将所有Firebase相关的变量名修改为以_开头的格式，比如：
   • _FIREBASE_API_KEY
   • _FIREBASE_AUTH_DOMAIN
   • 以此类推，确保和你cloudbuild.yaml中substitutions部分的变量名完全一致
4. 保存触发器，重新触发构建即可

二、环境变量管理优化方案 #

方案1：使用Secret Manager存储敏感数据（更安全） #

触发器替换变量会以明文形式存储，敏感密钥建议用Secret Manager管理：

步骤：

1. 在Secret Manager中为每个Firebase密钥创建独立的Secret，比如：
   • 密钥ID：firebase-api-key，值为你的Firebase API Key
   • 密钥ID：firebase-auth-domain，值为你的Auth Domain
2. 给Cloud Build服务账号添加roles/secretmanager.secretAccessor权限（确保能读取Secret）
3. 修改cloudbuild.yaml，直接从Secret Manager读取密钥并设置为环境变量，无需手动创建.env：

steps:
  - name: "gcr.io/cloud-builders/npm"
    dir: "dev"
    args: ["install"]

  - name: "gcr.io/cloud-builders/gcloud"
    dir: "dev"
    entrypoint: "bash"
    args:
      - "-c"
      - |
        set -e
        # 从Secret Manager获取密钥并设置为环境变量
        export FIREBASE_API_KEY=$(gcloud secrets versions access latest --secret=firebase-api-key)
        export FIREBASE_AUTH_DOMAIN=$(gcloud secrets versions access latest --secret=firebase-auth-domain)
        export FIREBASE_PROJECT_ID=$(gcloud secrets versions access latest --secret=firebase-project-id)
        export FIREBASE_STORAGE_BUCKET=$(gcloud secrets versions access latest --secret=firebase-storage-bucket)
        export FIREBASE_MESSAGING_SENDER_ID=$(gcloud secrets versions access latest --secret=firebase-messaging-sender-id)
        export FIREBASE_APP_ID=$(gcloud secrets versions access latest --secret=firebase-app-id)
        
        # 直接执行构建，无需生成.env文件
        npm run build

  - name: "gcr.io/cloud-builders/gcloud"
    dir: "dev"
    args: ["app", "deploy", "--project=my-project", "--appyaml=app.yaml"]

timeout: "1200s"
options:
  logging: CLOUD_LOGGING_ONLY

方案2：直接传递环境变量，避免生成.env文件 #

如果你的前端框架（如Vite、Create React App）支持读取构建时的环境变量，可以直接在构建步骤中注入变量，省去创建.env的步骤：

修改cloudbuild.yaml的构建步骤：

- name: "gcr.io/cloud-builders/npm"
    dir: "dev"
    env:
      - "FIREBASE_API_KEY=${_FIREBASE_API_KEY}"
      - "FIREBASE_AUTH_DOMAIN=${_FIREBASE_AUTH_DOMAIN}"
      - "FIREBASE_PROJECT_ID=${_FIREBASE_PROJECT_ID}"
      - "FIREBASE_STORAGE_BUCKET=${_FIREBASE_STORAGE_BUCKET}"
      - "FIREBASE_MESSAGING_SENDER_ID=${_FIREBASE_MESSAGING_SENDER_ID}"
      - "FIREBASE_APP_ID=${_FIREBASE_APP_ID}"
      # 注意：如果是Vite项目，变量需要以VITE_开头；React项目以REACT_APP_开头
      # - "VITE_FIREBASE_API_KEY=${_FIREBASE_API_KEY}"
    args: ["run", "build"]

同时修改你的Firebase初始化代码，直接读取对应变量：

import { initializeApp } from "firebase/app"
import { getFirestore } from "firebase/firestore"

// 根据框架调整变量前缀，比如Vite用import.meta.env，React用process.env
const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY || process.env.FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN || process.env.FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID || process.env.FIREBASE_PROJECT_ID,
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET || process.env.FIREBASE_STORAGE_BUCKET,
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID || process.env.FIREBASE_MESSAGING_SENDER_ID,
  appId: import.meta.env.VITE_FIREBASE_APP_ID || process.env.FIREBASE_APP_ID
}

const app = initializeApp(firebaseConfig)
const db = getFirestore(app)

这样既简化了构建流程，又避免了在构建过程中生成敏感文件。

内容的提问来源于stack exchange，提问作者C Knight