Azure SWA部署的纯前端应用无法获取环境变量值问题

核心规则先明确 #

Vite仅会将带VITE_前缀的环境变量暴露给前端代码，所以变量名必须以VITE_开头，不带前缀的变量无论本地还是Azure上都无法读取。

Azure SWA配置的关键误区 #

Vite是构建时注入环境变量，而非运行时读取。Azure SWA的应用设置（Configuration）里的变量，默认不会自动传递到构建环节，分两种部署场景处理：

场景1：通过GitHub/GitLab Actions自动部署 #

• 在Workflow的构建步骤中，必须将Azure配置的变量（或仓库Secrets）显式传递给npm run build命令。示例：

  - name: Build
    run: npm run build
    env:
      VITE_GOOGLE_MAPS_KEY: ${{ secrets.VITE_GOOGLE_MAPS_KEY }}
      VITE_EMAILJS_SERVICE_ID: ${{ secrets.VITE_EMAILJS_SERVICE_ID }}
  

• 确保Azure配置的变量已同步到仓库Secrets，或者直接在Workflow中引用Azure的环境变量（若使用Azure DevOps管道）。

场景2：手动上传构建产物 #

• 本地构建时必须先设置好环境变量（比如创建.env.production文件，或者终端临时设置），执行npm run build后再上传dist文件夹。因为构建后的代码已将变量硬编码，Azure的配置无法再修改已构建的代码。

代码读取方式检查 #

代码中必须使用Vite指定的方式读取变量，不能用process.env：

// 正确写法
const googleMapsKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
console.log(googleMapsKey);

// 错误写法（Vite默认不支持）
const wrongKey = process.env.GOOGLE_MAPS_API_KEY;

排查步骤 #

1. 本地执行npm run build，启动本地静态服务器（比如npx serve dist），检查变量是否能正常读取。如果本地构建后也读不到，说明Vite配置或变量名有误。
2. 若本地构建正常，检查Azure部署时的构建环节是否传入了正确的环境变量。可以查看部署日志，确认构建命令执行时环境变量是否存在。

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