在NextJS App Router/服务器组件中如何使用Docker运行时环境变量？

Pages Router 中的现有方式 #

使用 Pages Router 时，运行时获取环境变量有多种可行途径：

• 使用 react-env、next-runtime-env 这类工具
• 在 getStaticProps 中直接读取环境变量

App Router 服务器组件的问题 #

升级到 Next.js 13+ 的 App Router 后，服务器组件如何在运行时获取环境变量成为困扰。目前两种常见方案都存在明显缺陷：

• 在 Dockerfile 的 ENTRYPOINT 中执行项目构建：会导致容器启动缓慢，且镜像体积大幅增加
• 搜索替换法：虽能适配 App Router，但实现方式粗糙，不够优雅

推荐的优化方案 #

1. 服务器组件直接读取 process.env #

服务器组件运行在服务端，无需暴露给客户端，因此可以直接通过 process.env 读取环境变量，无需额外工具或配置：

// app/page.js（服务器组件）
export default function Home() {
  const apiUrl = process.env.API_URL; // 敏感变量也可直接读取，不会暴露给前端
  return <div>API 地址：{apiUrl}</div>;
}

若需将变量传递给客户端组件，通过 props 传递即可，避免敏感信息泄露。

2. 利用 runtimeConfig 实现动态配置 #

在 next.config.js 中配置 runtimeConfig，支持运行时动态读取环境变量，适配 Docker 等需要动态配置的部署场景：

// next.config.js
module.exports = {
  runtimeConfig: {
    // 仅服务器端可访问的敏感变量
    apiUrl: process.env.API_URL,
    // 客户端也可访问的公开变量
    publicAppName: process.env.NEXT_PUBLIC_APP_NAME,
  },
};

在服务器组件中读取配置：

// app/page.js
import getConfig from 'next/config';

const { serverRuntimeConfig, publicRuntimeConfig } = getConfig();

export default function Home() {
  return (
    <div>
      <p>服务器API地址：{serverRuntimeConfig.apiUrl}</p>
      <p>应用名称：{publicRuntimeConfig.publicAppName}</p>
    </div>
  );
}

这种方式无需重新构建项目，即可在运行时更新环境变量。

3. 自定义API路由统一管理配置 #

如果需要更灵活的配置管理（比如多环境动态切换），可以创建API路由作为配置中转：

// app/api/config/route.js
export async function GET() {
  const appConfig = {
    apiBaseUrl: process.env.API_URL,
    appVersion: process.env.NEXT_PUBLIC_APP_VERSION,
  };
  return Response.json(appConfig);
}

在服务器组件中调用该API获取配置：

// app/page.js
export default async function Home() {
  const res = await fetch(`${process.env.NEXT_PUBLIC_APP_URL}/api/config`);
  const config = await res.json();
  return <div>API 地址：{config.apiBaseUrl}</div>;
}

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