Docker化Next.js+Node.js项目：构建阶段无法连接后端API报错排查

在Docker化Node.js后端与Next.js前端项目过程中，期望Next.js在构建阶段从后端获取JSON文件生成静态页面，但执行docker-compose up -d --build时出现连接127.0.0.1:5000被拒绝（ECONNREFUSED）的错误。以下是项目配置文件、错误日志及解决方案：

项目配置文件 #

./client/Dockerfile #

FROM node:latest AS builder

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:1.25
COPY --from=builder /app/.next /usr/share/nginx/html

./server/Dockerfile #

FROM node:latest

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

EXPOSE 5000
CMD ["node", "dist/app.js"]

./proxy/Dockerfile #

FROM nginx:1.25
COPY default.conf /etc/nginx/conf.d

./proxy/default.conf #

server {
  listen 80;
  server_name localhost;
  
  location / {
    proxy_pass http://frontend:80/;
  }

  location /api/ {
    proxy_pass http://backend:5000/;
  }
}

./docker-compose.yml #

services:
  frontend:
    build: ./client
    ports: ['8001:80']
  backend:
    build: ./server
    ports: ['8002:5000']
  proxy:
    build: ./proxy
    ports: ['8000:80']

错误日志 #

34.47  ✓ Compiled successfully
34.47    Collecting page data ...
35.29 Error loading parts TypeError: fetch failed
35.29     at node:internal/deps/undici/undici:13484:13
35.29     at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
35.29     at async s (/app/.next/server/pages/parts.js:1:8694)
35.29     at async d (/app/.next/server/pages/parts.js:1:13445)
35.29     at async buildStaticPaths (/app/node_modules/next/dist/build/utils.js:788:33)
35.29     at async /app/node_modules/next/dist/build/utils.js:1220:110
35.29     at async Span.traceAsyncFn (/app/node_modules/next/dist/trace/trace.js:154:20) {
35.29   [cause]: Error: connect ECONNREFUSED 127.0.0.1:5000
35.29       at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1615:16) {
35.29     errno: -111,
35.29     code: 'ECONNREFUSED',
35.29     syscall: 'connect',
35.29     address: '127.0.0.1',
35.29     port: 5000
35.29   }
35.29 }

问题原因及解决方案 #

核心问题 #

1. 构建阶段网络隔离：Next.js的npm run build是在前端容器的镜像构建阶段执行的，此时后端容器尚未启动，且构建阶段与Docker Compose的服务网络完全隔离，无法访问后端服务。
2. 地址指向错误：前端代码中使用127.0.0.1:5000请求后端，在容器内部127.0.0.1指向容器自身，而非后端服务容器。

解决方案 #

方案1：调整构建流程，依赖后端服务启动后再构建

修改前端构建时机为容器启动阶段，并使用Docker内部服务名访问后端：

1. 修改前端代码中的请求地址，将http://127.0.0.1:5000改为http://backend:5000（Docker Compose内部服务名）。
2. 更新./client/Dockerfile，将构建步骤移到容器启动时执行：

FROM node:latest

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

# 先构建再启动服务
CMD npm run build && npm run start

3. 更新docker-compose.yml，添加依赖关系和统一网络：

services:
  frontend:
    build: ./client
    ports: ['8001:3000']
    depends_on:
      - backend
    networks:
      - app-network
  backend:
    build: ./server
    ports: ['8002:5000']
    networks:
      - app-network
  proxy:
    build: ./proxy
    ports: ['8000:80']
    depends_on:
      - frontend
      - backend
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

方案2：静态复制后端数据到前端构建环境

如果后端JSON文件是静态的，可直接复制到前端项目，避免构建时请求后端：

1. 在./client/Dockerfile中添加复制步骤：

FROM node:latest AS builder

WORKDIR /app
COPY package*.json ./
RUN npm install
# 复制后端JSON文件到前端项目目录
COPY ../server/path/to/data.json ./static-data/
COPY . .
RUN npm run build

FROM nginx:1.25
COPY --from=builder /app/.next /usr/share/nginx/html

2. 修改前端代码，直接读取本地JSON文件而非调用后端接口。

方案3：通过构建参数传递后端地址

使用Docker Compose的构建参数传递后端服务地址：

1. 更新docker-compose.yml：

services:
  frontend:
    build:
      context: ./client
      args:
        - BACKEND_URL=http://backend:5000
    ports: ['8001:80']
    depends_on:
      - backend
    networks:
      - app-network
  # 其他服务配置不变

2. 更新./client/Dockerfile接收并注入环境变量：

FROM node:latest AS builder

ARG BACKEND_URL
# 注入Next.js可访问的环境变量
ENV NEXT_PUBLIC_BACKEND_URL=$BACKEND_URL

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:1.25
COPY --from=builder /app/.next /usr/share/nginx/html

3. 前端代码中使用process.env.NEXT_PUBLIC_BACKEND_URL作为请求地址。

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