如何在Next.js执行next start时为React应用填充环境变量（Docker多环境）

核心思路 #

要实现"一次构建、多环境部署"，必须让环境变量在next start运行阶段而非构建阶段注入并生效。以下是三种可落地的方案：

方案1：运行时导出环境变量（App/Page Router通用） #

1. 在项目根目录创建src/runtime-env.js（或任意路径），内容如下：

   export const runtimeEnv = {
     API_URL: process.env.API_URL,
     APP_NAME: process.env.APP_NAME
   };
   

2. 在React组件中直接导入使用，示例：

   import { runtimeEnv } from '../runtime-env';
   
   export default function Home() {
     return <div>当前API地址：{runtimeEnv.API_URL}</div>;
   }
   

3. 部署时，在Google Cloud Run的服务配置中直接添加所需环境变量，next start启动时会自动读取容器内的环境变量，该文件会在运行时动态获取最新值。

方案2：Docker入口脚本动态生成前端配置 #

1. 创建entrypoint.sh脚本，用于启动前生成前端可访问的环境变量配置：

   #!/bin/sh
   # 生成全局环境变量配置文件
   cat > /app/public/runtime-env.js << EOF
   window.__RUNTIME_ENV__ = {
     API_URL: "$API_URL",
     APP_NAME: "$APP_NAME"
   };
   EOF
   # 启动Next.js服务
   exec next start
   

2. 修改Dockerfile，将脚本设为入口：

   # 假设已完成构建阶段，以下是运行阶段配置
   FROM node:18-alpine
   WORKDIR /app
   COPY --from=builder /app/.next ./.next
   COPY --from=builder /app/public ./public
   COPY --from=builder /app/node_modules ./node_modules
   COPY --from=builder /app/package.json ./package.json
   # 添加并执行入口脚本
   COPY entrypoint.sh /app/entrypoint.sh
   RUN chmod +x /app/entrypoint.sh
   ENTRYPOINT ["/app/entrypoint.sh"]
   

3. 在React组件中直接访问全局变量：

   export default function Home() {
     return <div>应用名称：{window.__RUNTIME_ENV__.APP_NAME}</div>;
   }
   

方案3：Server Components传递环境变量（App Router专属） #

如果使用Next.js 13+ App Router，可利用Server Components在运行时读取环境变量，再传递给客户端组件：

1. 服务端组件直接读取环境变量：

   // app/page.js（默认是Server Component，无需加'use client'）
   export default function Home() {
     const apiUrl = process.env.API_URL;
     return <ClientComponent apiUrl={apiUrl} />;
   }
   

2. 客户端组件接收参数使用：

   // app/ClientComponent.js
   'use client';
   export default function ClientComponent({ apiUrl }) {
     return <div>API地址：{apiUrl}</div>;
   }
   

关键注意事项 #

• 禁用next.config.js中的env和publicRuntimeConfig配置，这些会将变量固化在构建产物中，无法在运行时修改。
• Google Cloud Run配置环境变量时，直接在服务的"环境变量"面板添加键值对即可，无需修改镜像。

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