docker-compose.yml环境变量传入客户端Next.js失败如何解决

• 核心问题出在Next.js对NEXT_PUBLIC_前缀环境变量的处理机制：这类变量属于构建时静态注入变量，会在执行next build编译项目的阶段，直接被硬编码替换到最终的JS产物中，不会在容器启动、服务运行阶段从系统环境动态读取。
• 你当前在docker-compose.yml的environment字段下配置的变量，仅会在容器启动运行阶段注入容器环境，但你使用的nextjs-client镜像是提前构建完成的，构建阶段没有获取到该变量值，编译后的代码里对应取值位置就会被固定为undefined，运行时再注入环境变量不会改变已经编译完成的代码。
• 配置里还有一处语法问题：ports字段需要写成数组格式，直接写字符串会导致端口映射规则不生效。

根据你的使用场景二选一即可：

方案1：构建阶段传入环境变量（常规场景推荐） #

NEXT_PUBLIC_前缀的变量必须在构建阶段传入，调整配置如下：

1. 修改docker-compose.yml，把变量移到build参数下，同时修正ports写法：

services:
  nextjs-client:
    build:
      context: ./  # 替换为你Next.js项目Dockerfile所在的实际目录
      args:
        - NEXT_PUBLIC_API_HOST=192.168.0.9:8080
    ports:
      - "3000:3000"

2. 调整项目对应的Dockerfile，声明构建参数并传递给构建过程：

# 省略前面的基础镜像、依赖安装步骤，例：FROM node:18-alpine AS builder
ARG NEXT_PUBLIC_API_HOST
# 将构建参数转为环境变量，保证next build执行时能读取到
ENV NEXT_PUBLIC_API_HOST=$NEXT_PUBLIC_API_HOST
# 执行项目构建
RUN npm run build
# 省略后续的生产镜像启动步骤

3. 执行命令重新构建镜像再启动即可：

docker-compose build --no-cache nextjs-client
docker-compose up -d nextjs-client

后续如果修改该变量值，必须重新执行构建命令才能生效。

方案2：改用运行时配置（适合需要频繁调整变量、不想重复构建镜像的场景） #

如果不想每次修改变量都重新打镜像，可以放弃静态NEXT_PUBLIC_变量，改用Next.js原生的运行时配置能力：

1. 修改项目根目录的next.config.js，声明运行时可读取的公共配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  publicRuntimeConfig: {
    apiHost: process.env.NEXT_PUBLIC_API_HOST,
  },
}
module.exports = nextConfig

2. 调整代码里的取值方式，不要直接读process.env，改为从next/config模块读取：

import getConfig from 'next/config'
const { publicRuntimeConfig } = getConfig()
// 实际取值
const API_HOST = publicRuntimeConfig.apiHost

3. 保留你原来在docker-compose.yml的environment字段下的变量配置，修正ports写法即可，后续修改变量只需要重启容器，不需要重新构建镜像。

注意：Next.js 13+ App Router模式下使用客户端组件时，需要额外在服务端组件读取配置后通过props传递给客户端组件，避免客户端取不到值。

内容的提问来源于stack exchange，提问作者k-wasilewski