如何通过Google Cloud Build部署带环境变量的Vue.js应用至Firebase Hosting

最近帮朋友排查过一模一样的问题，折腾了一阵终于理清了解决方案和踩过的坑，分享给你：

核心矛盾点 #

你遇到的冲突本质是两个工具的环境变量规则不兼容：

• Vue.js 只会识别以VUE_APP_为前缀的环境变量，其他前缀的变量会被直接忽略
• Google Cloud Build 的自定义替换变量要求以_开头（比如_FIREBASE_WEB_API_KEY），否则会抛出"key in the template is not a valid built-in substitution"的错误

你之前配置的问题所在 #

你最初的尝试有两个关键错误：

1. 执行的是npm ci命令——Vue.js的环境变量是在构建阶段（也就是npm run build）注入到打包产物里的，ci只是安装依赖，这一步注入变量完全没用
2. 额外添加的echo $VUE_APP_FIREBASE_WEB_API_KEY命令没有开启ALLOW_LOOSE替换选项，Cloud Build会把VUE_APP_开头的变量误判为内置替换变量，从而触发错误

正确的Cloud Build配置 #

以下是经过验证可以正常工作的配置，我把依赖安装、构建、部署步骤都整合好了：

steps:
  # 第一步：安装项目依赖（这一步不需要注入环境变量）
  - name: 'gcr.io/cloud-builders/npm'
    args: [ 'ci', '--prefix', 'web/vue_js_landing/' ]
  
  # 第二步：构建Vue项目，这里注入Vue需要的环境变量
  - name: 'gcr.io/cloud-builders/npm'
    args: [ 'run', 'build', '--prefix', 'web/vue_js_landing/' ]
    env:
      - 'VUE_APP_FIREBASE_WEB_API_KEY=${_FIREBASE_WEB_API_KEY}'
  
  # 第三步：部署到Firebase Hosting
  - name: 'gcr.io/cloud-builders/firebase'
    args: [ 'deploy', '--only', 'hosting', '--project', '$PROJECT_ID' ]

额外注意事项 #

• 必须在构建步骤注入变量：记住，Vue的环境变量是静态打包进代码的，只有在npm run build过程中注入才会生效，依赖安装阶段注入完全没用
• 调试变量需开启ALLOW_LOOSE：如果你需要在Cloud Build步骤里直接打印VUE_APP_前缀的变量（比如用echo调试），需要在cloudbuild.yaml顶部添加以下配置，否则会触发校验错误：

options:
  substitution_option: ALLOW_LOOSE

• Cloud Build触发器配置：别忘了在你的Cloud Build触发器的「替换变量」里添加_FIREBASE_WEB_API_KEY，并设置好对应的变量值

验证是否生效 #

部署完成后，打开浏览器开发者工具的「Sources」面板，搜索打包后的JS文件里的VUE_APP_FIREBASE_WEB_API_KEY，如果能看到你设置的变量值，就说明配置成功了。

内容的提问来源于stack exchange，提问作者Andreas Tzionis