在Azure静态Web Apps与Next.js中优化客户端环境变量配置

问题背景 #

从Vercel迁移Next.js 14.2.3（pages目录）到Azure静态Web Apps后，客户端环境变量无法像在Vercel那样直接通过process.env.NEXT_PUBLIC_*访问。当前采用的方案需同步Azure环境变量到GitHub Secrets、配置GitHub Actions的env节点、修改next.config.js并给每个页面添加空getServerSideProps，流程繁琐，寻求更优解。

方案1：复用Next.js原生NEXT_PUBLIC_变量机制（推荐） #

Azure静态Web Apps支持直接将门户配置的环境变量注入构建流程，完全对齐Vercel的用法：

1. 打开Azure静态Web Apps门户，进入配置 > 环境变量
2. 添加带NEXT_PUBLIC_前缀的变量（如NEXT_PUBLIC_URL、NEXT_PUBLIC_API_URL），变量名必须保留NEXT_PUBLIC_前缀（Next.js会自动识别并注入客户端）
3. 修改GitHub Actions部署yml文件，删除Build And Deploy步骤中的env节点配置（Azure会自动注入门户配置的构建时变量）
4. 删除next.config.js中的publicRuntimeConfig配置，同时移除所有页面的getServerSideProps和getConfig调用
5. 直接在组件中使用process.env.NEXT_PUBLIC_URL访问变量，和Vercel用法完全一致

验证：重新触发部署，构建阶段Azure会自动将变量注入Next.js构建流程，客户端可直接读取。

方案2：动态环境变量（支持部署后修改） #

若需无需重新构建即可修改环境变量，可使用Azure应用设置配合动态加载：

1. 在Azure门户配置 > 应用设置添加变量（无需NEXT_PUBLIC_前缀，如APP_URL、API_URL）
2. 在项目public目录创建env.js文件：

window.env = {
  APP_URL: "${APP_URL}",
  API_URL: "${API_URL}"
};

3. 在Azure应用设置中添加SWA_CUSTOM_ENV_VARS变量，值为APP_URL,API_URL，告知Azure替换env.js中的占位符
4. 在_app.js中引入该文件：

import '../public/env.js';

5. 组件中通过window.env.APP_URL访问变量，修改Azure应用设置后立即生效，无需重新构建

方案3：简化现有流程（过渡方案） #

若暂时不想调整架构，可通过React Context消除每个页面的getServerSideProps：

1. 修改_app.js，将publicRuntimeConfig通过Context传递：

// _app.js
import getConfig from 'next/config';
import { createContext, useContext } from 'react';

const EnvContext = createContext();

export default function MyApp({ Component, pageProps }) {
  const { publicRuntimeConfig } = getConfig();
  return (
    <EnvContext.Provider value={publicRuntimeConfig}>
      <Component {...pageProps} />
    </EnvContext.Provider>
  );
}

// 自定义Hook方便全局调用
export const useEnv = () => useContext(EnvContext);

2. 页面中直接使用自定义Hook获取变量：

import { useEnv } from '../_app';

const Page = () => {
  const { NEXT_PUBLIC_URL, NEXT_PUBLIC_API_URL } = useEnv();
  return (
    <div>
      <p>{NEXT_PUBLIC_URL}</p>
      <p>{NEXT_PUBLIC_API_URL}</p>
    </div>
  );
};

export default Page;

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