如何在Azure Web Apps中为Next.js 14应用配置环境变量

核心原因 #

Next.js 的 next.config.js 是在构建阶段执行的，所有通过 process.env 引用的变量会被静态注入到构建产物中。如果 GitHub Workflows 构建过程中没有获取到 Azure 配置的环境变量，部署后 next.config.js 自然无法读取到这些值——哪怕 Azure 应用设置里已经配置了，也只是运行时可用，无法回溯到构建阶段。

解决步骤 #

1. 在 GitHub Workflows 构建阶段注入 Azure 环境变量 #

要让 next.config.js 读取到变量，必须在构建前把 Azure 的应用设置导入到构建环境中：

• 先确保 GitHub 仓库已配置 Azure 相关密钥（AZURE_WEBAPP_NAME、AZURE_RESOURCE_GROUP、AZURE_CREDENTIALS）。
• 在 Workflow 的构建步骤前添加脚本，拉取 Azure 应用设置并导出为环境变量：

- name: 安装依赖工具
  run: sudo apt-get install -y jq

- name: 拉取Azure应用设置并注入环境
  run: |
    az login --service-principal -u ${{ secrets.AZURE_CLIENT_ID }} -p ${{ secrets.AZURE_CLIENT_SECRET }} --tenant ${{ secrets.AZURE_TENANT_ID }}
    az webapp config appsettings list --name ${{ secrets.AZURE_WEBAPP_NAME }} --resource-group ${{ secrets.AZURE_RESOURCE_GROUP }} | jq -r '.[] | "export \(.name)=\(.value)"' > appsettings.sh
    source appsettings.sh

- name: 构建Next.js应用
  run: npm run build

2. 区分构建时与运行时变量 #

• 构建时变量（next.config.js 中使用的）：必须在构建阶段暴露，按上一步操作执行即可。
• 运行时变量（API 路由、Server Components 中使用的）：无需额外处理，Azure 应用设置中的变量会自动注入到运行环境，直接用 process.env.VAR_NAME 即可读取。

3. 放弃启动脚本创建 .env.production 的尝试 #

构建完成后再创建 .env.production 完全无效，因为 next.config.js 的逻辑已经在构建阶段执行完毕，运行时的 .env 文件不会影响已生成的构建产物。

4. 检查部署动作的参数 #

如果使用 azure/webapps-deploy@v2 动作，不要在 app-settings 参数中覆盖或遗漏需要的变量，否则会清空 Azure 原有配置。如果需要同步变量，确保参数包含所有必要键值对：

- name: 部署到Azure Web Apps
  uses: azure/webapps-deploy@v2
  with:
    app-name: ${{ secrets.AZURE_WEBAPP_NAME }}
    publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
    app-settings: |
      VAR_NAME=${{ secrets.VAR_NAME }}
      ANOTHER_VAR=${{ secrets.ANOTHER_VAR }}

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