如何实现Next.js项目Docker镜像的动态环境变量配置？

你的核心问题是Next.js默认会把构建时传入的环境变量嵌入到静态编译产物中，导致镜像固化了变量值，无法在运行时修改。要实现运行时动态传参，关键是让环境变量在容器启动时才被读取，而非构建阶段。以下是几种可行方案：

方案1：使用Next.js运行时配置（Pages Router） #

适用于传统Pages Router项目，通过publicRuntimeConfig让客户端代码在运行时读取环境变量：

1. 修改next.config.js，配置运行时可访问的变量：

module.exports = {
  publicRuntimeConfig: {
    backendUrl: process.env.BACKEND_URL || 'http://default-backend.example.com'
  }
};

2. 在组件中读取运行时配置：

import getConfig from 'next/config';

const { publicRuntimeConfig } = getConfig();

export default function Home() {
  return <div>后端地址：{publicRuntimeConfig.backendUrl}</div>;
}

方案2：App Router 运行时变量传递（Next.js 13+） #

如果用App Router，服务器组件可直接读取process.env，再传递给客户端组件：

1. 服务器组件（无需'use client'）读取环境变量：

// app/page.js
export default function Home() {
  const backendUrl = process.env.BACKEND_URL || 'http://default-backend.example.com';
  return <ClientComponent backendUrl={backendUrl} />;
}

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

// app/components/ClientComponent.jsx
'use client';

export default function ClientComponent({ backendUrl }) {
  return <div>后端地址：{backendUrl}</div>;
}

方案3：启动前生成客户端可访问的配置文件 #

如果需要客户端直接读取环境变量（无需服务器组件中转），可在容器启动时生成静态配置文件：

1. 创建启动脚本start.sh：

#!/bin/sh

# 将环境变量写入public目录下的配置文件
echo "window.__APP_ENV__ = { BACKEND_URL: '$BACKEND_URL' };" > /app/public/env-config.js

# 启动Next.js应用
npm start

2. 修改Dockerfile，替换启动命令：

FROM node:alpine as build-stage

COPY . /app
WORKDIR /app

RUN npm install --silent
# 构建阶段无需传入环境变量
RUN npm run build

FROM node:alpine as production-stage

COPY --from=build-stage /app /app
COPY start.sh /app/start.sh
RUN chmod +x /app/start.sh

WORKDIR /app
CMD ["/app/start.sh"]

EXPOSE 3000

3. 客户端组件读取全局配置：

'use client';

export default function Home() {
  const backendUrl = window.__APP_ENV__.BACKEND_URL || 'http://default-backend.example.com';
  return <div>后端地址：{backendUrl}</div>;
}

通用Dockerfile修改要点 #

不管用哪种方案，都需要移除构建阶段的ARG和ENV声明，确保构建时不固化变量：

# 移除构建阶段的ARG BACKEND_URL和ENV BACKEND_URL=$BACKEND_URL
FROM node:alpine as build-stage

COPY . /app
WORKDIR /app

RUN npm install --silent
RUN npm run build

FROM node:alpine as production-stage

COPY --from=build-stage /app /app

WORKDIR /app
CMD ["npm", "start"]

EXPOSE 3000

现在你可以直接执行docker build -t my-app .构建镜像，运行时通过docker run --env BACKEND_URL=https://your-real-backend.com -p 3000:3000 my-app指定变量即可。

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