React NextJS容器在Docker Compose中无法读取构建参数，如何传递后端URL？

问题描述 #

我有一个包含Next.js前端和Python后端API的代码仓库，尝试通过Docker Compose将后端URL传递给前端，但前端中process.env为空对象。现有配置如下：

docker-compose.yml #

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
      args:
        - NEXT_PUBLIC_BACKEND_BASE_URL=http://backend:80
    restart: always
    ports:
      - 80:3000

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - 8080:80
    ....

前端Dockerfile #

FROM node:20
WORKDIR /app

ARG NEXT_PUBLIC_BACKEND_BASE_URL
ENV NEXT_PUBLIC_BACKEND_BASE_URL=$NEXT_PUBLIC_BACKEND_BASE_URL

COPY ./package*.json ./
COPY .npmrc .npmrc
RUN npm i
COPY . .

RUN npm run build

CMD [ "npm", "start" ]

请问我遗漏了什么配置？这是向React传递后端URL的最佳方式吗？

问题排查与解决方案 #

1. 遗漏的关键配置 #

你当前的核心问题大概率是以下其中一点：

• 环境变量访问方式错误：Next.js仅会将带有NEXT_PUBLIC_前缀的环境变量暴露给客户端代码，必须确保代码中是通过process.env.NEXT_PUBLIC_BACKEND_BASE_URL访问，而非不带前缀的变量名。
• Docker构建缓存干扰：旧的构建缓存可能没有包含新注入的环境变量，执行docker-compose build --no-cache frontend重新构建前端镜像，清除缓存后再测试。
• Next.js版本兼容问题：部分旧版Next.js对构建时环境变量的处理存在差异，建议升级到v13及以上版本。

你的Dockerfile和docker-compose配置本身是正确的（ARG传递+ENV持久化，且在build前设置了环境变量），所以优先排查上述几点。

2. 是否为最佳方式？ #

这种构建时注入环境变量的方式适合固定部署环境，但并非最灵活的方案：

• 优点：无需在代码中硬编码URL，构建时一次性注入，适合单一环境部署。
• 缺点：如果需要切换后端URL，必须重新构建前端镜像，无法在运行时动态调整。

更优方案推荐

方案一：运行时动态配置（适用于需要频繁切换环境的场景）

Next.js在生产构建时会把NEXT_PUBLIC_变量打包进静态文件，运行时修改不会生效。可以通过以下方式实现动态配置：

1. 在前端项目的public目录下创建config.json：

   {
     "backendBaseUrl": "http://backend:80"
   }
   

2. 在容器启动时，通过脚本替换该文件的内容（在Dockerfile中添加启动脚本）：

   FROM node:20
   WORKDIR /app
   
   COPY ./package*.json ./
   COPY .npmrc .npmrc
   RUN npm i
   COPY . .
   
   RUN npm run build
   
   # 添加启动脚本
   COPY start.sh .
   RUN chmod +x start.sh
   
   CMD [ "./start.sh" ]
   

3. start.sh内容：

   #!/bin/sh
   # 替换config.json中的URL
   sed -i "s|http://backend:80|$NEXT_PUBLIC_BACKEND_BASE_URL|g" public/config.json
   # 启动Next.js服务
   npm start
   

4. 修改docker-compose.yml，直接传递运行时环境变量：

   frontend:
     build: ./frontend
     restart: always
     ports:
       - 80:3000
     environment:
       - NEXT_PUBLIC_BACKEND_BASE_URL=http://backend:80
   

5. 前端代码中通过fetch读取/config.json获取URL：

   const getBackendUrl = async () => {
     const res = await fetch('/config.json');
     const config = await res.json();
     return config.backendBaseUrl;
   };
   

方案二：利用Docker内部网络（适合固定环境）

由于前端和后端在同一个Docker Compose默认网络中，可以直接通过服务名+端口访问后端，无需传递环境变量，代码中直接写http://backend:80即可。但这种方式耦合度高，仅适合无需切换环境的场景。

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