GitHub Actions中React+Firebase部署时如何让.env环境变量生效?
问题核心根因
本地执行firebase deploy完全正常,但GitHub Actions自动部署后API key报无效,本质是两个配置错位导致的:
.gitignore默认规则会强制忽略项目根目录下所有.env.*文件,本地存在的.env.production根本没有推送到GitHub仓库,Actions拉取代码时自然读不到文件里的配置值- Firebase CLI初始化时自动生成的两个托管工作流,没有在项目构建阶段将GitHub Secrets中的配置值注入到最终打包产物中。React类前端项目的环境变量是构建期静态注入的,并非运行时动态读取系统环境变量——哪怕Secrets配置完全正确,只要没在执行构建命令的步骤显式映射,打包出来的JS文件里的API key就是空值或默认占位符,自然会触发密钥校验错误。
正确的环境变量配置流程
- 校验本地文件提交状态
检查.gitignore规则,确认不要将包含真实配置值的.env.production直接提交到仓库,避免密钥泄露。这类敏感配置要完全通过GitHub Secrets在CI流程中动态传递。 - 配置仓库级Secrets
进入仓库设置的Actions Secrets板块,将本地.env.production中需要的所有Firebase配置项(Firebase API Key、Auth Domain、Project ID等)逐字段添加为Repository Secret,键名和本地文件中的变量名保持完全一致。 - 修改默认生成的两个工作流配置
针对.github/workflows/下的firebase-hosting-merge.yml和firebase-hosting-pull-request.yml,定位到执行依赖安装、源码构建的步骤,在构建命令的同级位置声明env映射,将GitHub Secrets值传递给构建过程,参考结构:
配置时需要注意几个高频踩坑点:- name: 安装依赖并构建产物 run: npm ci && npm run build env: REACT_APP_FIREBASE_API_KEY: ${{ secrets.REACT_APP_FIREBASE_API_KEY }} REACT_APP_FIREBASE_AUTH_DOMAIN: ${{ secrets.REACT_APP_FIREBASE_AUTH_DOMAIN }} # 逐行列出所有项目需要的Firebase环境变量,键名和本地.env.production完全匹配- 基于Create React App的项目,环境变量必须以
REACT_APP_为前缀才会被Webpack注入到打包产物中;基于Vite的项目,必须以VITE_为前缀,否则框架会直接忽略这些配置值 - env声明必须放在执行构建命令的步骤内部,不能只写在最终Deploy步骤的配置块里——Deploy动作发生在构建完成之后,此时静态资源已经打包结束,在Deploy阶段注入环境变量对最终产物没有任何作用
- 基于Create React App的项目,环境变量必须以
- 排除Secrets读取失效的常见场景
- 核对Secrets作用域:如果仓库启用了GitHub Environment环境隔离,需要确认对应的Secret已经关联到工作流运行时使用的环境,否则Actions会返回空的Secret值
- 核对变量名拼写:大小写、特殊字符要和本地使用的变量名完全一致,差一个字符都会导致构建时读不到对应值
- 核对工作流部署路径:Firebase默认生成的工作流默认托管
public目录,如果你的项目构建产物输出在build或dist目录,需要在firebase.json里配置正确的public路径,避免部署未经过环境变量注入的源码目录
快速有效性验证方法
- 在工作流的构建步骤中临时添加一行环境变量打印命令,比如在构建命令前加
printenv | grep REACT_APP_,手动触发一次工作流后查看步骤日志,如果能输出你配置的Secret值,说明环境变量传递链路正常;如果输出为空,说明是Secrets的权限或作用域配置错误 - 部署完成后访问站点,打开开发者工具找到加载的JS资源,搜索其中的Firebase API Key字段,确认值和本地配置的正确值一致,避免打包产物中残留占位符或空值
内容的提问来源于stack exchange,提问作者Tarun Singh
相关产品推荐
相关产品推荐

