NextJS部署Azure后无法读取配置的环境变量求助

问题场景 #

通过GitHub Actions CI/CD流水线部署使用App Router的Next.js网站到Azure后，所有Azure配置的环境变量读取结果均为undefined。

现有配置信息 #

Azure环境变量配置 #

前端代码（客户端组件） #

"use client";
import React from "react";

const page = () => {
    console.log(process.env.NEXT_PUBLIC_API_KEY);
    console.log(process.env.PROJECT_1);
    console.log(process.env.NEXT_PUBLIC_React_app);
    return (
        <div>
            Next js app {process.env.NEXT_PUBLIC_API_KEY} {process.env.PROJECT_1}{" "}
            {process.env.NEXT_PUBLIC_React_app}{" "}
        </div>
    );
};

export default page;

GitHub Workflow配置 #

name: Azure Deployment

on:
  push:
    branches:
      - main  # Change this to your main branch name

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Install dependencies and build
        run: |
          npm install
          npm run build

      - name: Deploy to Azure
        uses: azure/webapps-deploy@v2
        with:
          app-name: your-app-name  # Replace with your Azure app name
          slot-name: production  # Replace with your slot name if applicable
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}  # Your Azure publish profile secret
          package: .next

问题原因 #

1. Next.js环境变量规则限制：客户端组件（标注"use client"）仅能读取以NEXT_PUBLIC_为前缀的环境变量，且这类变量是在构建阶段注入到代码中的。
2. CI/CD构建流程问题：当前Workflow在GitHub Actions中完成构建，构建过程无法获取Azure配置的环境变量，导致客户端代码中的process.env.NEXT_PUBLIC_*未被注入，部署后自然为undefined。
3. 变量名不匹配：Azure配置的变量名（如API_KEY、React_app）与代码中读取的变量名（NEXT_PUBLIC_API_KEY、NEXT_PUBLIC_React_app）不对应，且未遵循Next.js全大写的命名规范。

解决方案 #

方案1：在GitHub Actions构建阶段注入变量 #

适用于需要在GitHub端完成构建的场景：

1. 在GitHub仓库的「Secrets and variables」中添加对应变量：
   • NEXT_PUBLIC_API_KEY（值为next_public_api_key）
   • PROJECT_1（值为project_1，仅服务端组件可读取）
   • NEXT_PUBLIC_REACT_APP（值为new_react_app）
2. 修改Workflow的构建步骤，传递环境变量：

   - name: Install dependencies and build
     run: |
       npm install
       NEXT_PUBLIC_API_KEY=${{ secrets.NEXT_PUBLIC_API_KEY }} \
       PROJECT_1=${{ secrets.PROJECT_1 }} \
       NEXT_PUBLIC_REACT_APP=${{ secrets.NEXT_PUBLIC_REACT_APP }} \
       npm run build
   

3. 确保代码中读取的变量名与GitHub Secrets完全一致，统一使用大写字母+下划线的命名格式。

方案2：让Azure负责构建（推荐） #

适用于需要Azure环境变量参与构建的场景，无需在GitHub端维护变量：

1. 修改Workflow的部署步骤，改为部署整个代码仓库（让Azure执行构建）：

   - name: Deploy to Azure
     uses: azure/webapps-deploy@v2
     with:
       app-name: your-app-name
       slot-name: production
       publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
       package: .
   

2. 在Azure App Service的「配置 > 应用程序设置」中修正变量：
   • 客户端变量：NEXT_PUBLIC_API_KEY = next_public_api_key、NEXT_PUBLIC_REACT_APP = new_react_app
   • 服务端变量：PROJECT_1 = project_1
3. 重启Azure App Service，确保环境变量生效。

额外注意事项 #

• 客户端组件永远无法读取不带NEXT_PUBLIC_前缀的变量，代码中的process.env.PROJECT_1需移至服务端组件读取后，通过props传递给客户端。
• 环境变量名严格区分大小写，建议统一使用大写字母和下划线的格式，避免因大小写不匹配导致读取失败。

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