Docker容器间通信故障排查：NextJS13与.NET API连接失败

一、解决ECONNREFUSED错误（静态预渲染阶段） #

错误核心是NextJS在**静态预渲染（prerendering）**阶段发起API请求，此时后端容器尚未启动（构建阶段），或构建环境无法访问后端服务。

解决步骤： #

1. 区分构建时与运行时API调用
   在NextJS中，getStaticProps会在构建阶段执行，此时直接调用后端API会因后端未启动失败。修改代码，在构建时返回mock数据或跳过真实API调用：

   export async function getStaticProps() {
     let users;
     // 判断是否为构建环境
     const isBuild = process.env.NODE_ENV === 'production' || process.env.BUILD_MOCK === 'true';
     if (isBuild) {
       // 构建阶段使用mock数据
       users = [{ id: 1, name: 'Mock User' }, { id: 2, name: 'Test User' }];
     } else {
       // 运行时调用真实API
       const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/User`);
       users = await res.json();
     }
     return { props: { users } };
   }
   

2. 改用服务器端渲染（SSR）
   如果页面需要实时数据，将getStaticProps替换为getServerSideProps，API请求会在运行时发起，此时前端容器已运行，可正常访问Docker Compose中的backend服务：

   export async function getServerSideProps() {
     const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/User`);
     const users = await res.json();
     return { props: { users } };
   }
   

3. 检查Docker Compose配置
   确保两个服务在同一网络（Compose默认创建默认网络），并配置健康检查确保后端启动完成：

   services:
     backend:
       build: ./backend
       ports:
         - "8080:8080"
       # 健康检查，确保后端服务就绪
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
         interval: 5s
         timeout: 5s
         retries: 3
     frontend:
       build: ./frontend
       ports:
         - "3000:3000"
       depends_on:
         backend:
           condition: service_healthy # 等待后端健康检查通过再启动
       environment:
         - NEXT_PUBLIC_API_URL=http://backend:8080/api
   

二、解决GitHub Actions构建失败问题 #

在GitHub Actions的隔离环境中，构建前端时需确保后端服务已启动，或使用mock数据。

方案1：构建前启动后端服务 #

修改GitHub Actions workflow，先启动后端并等待其就绪，再构建前端：

name: Build and Deploy
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # 初始化Docker环境
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      # 启动后端服务
      - name: Start backend service
        run: docker compose up -d backend
      # 等待后端健康检查通过
      - name: Wait for backend to be ready
        run: |
          until docker compose exec backend curl -s http://localhost:8080/api/health; do
            sleep 2
          done
      # 构建前端
      - name: Build frontend
        run: docker compose build frontend
      # 清理资源
      - name: Clean up
        run: docker compose down

方案2：构建时使用mock数据 #

在GitHub Actions中设置环境变量，让前端构建时自动使用mock数据：

- name: Build frontend
  run: docker compose build frontend
  env:
    BUILD_MOCK: "true"

三、更简便的容器交互方式 #

1. 使用Traefik反向代理（推荐） #

通过Traefik统一入口，前端可使用相对路径调用API，无需硬编码后端主机名：

services:
  traefik:
    image: traefik:v2.10
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  backend:
    build: ./backend
    labels:
      - "traefik.http.routers.backend.rule=PathPrefix(`/api`)"
      - "traefik.http.services.backend.loadbalancer.server.port=8080"
  frontend:
    build: ./frontend
    labels:
      - "traefik.http.routers.frontend.rule=PathPrefix(`/`)"
      - "traefik.http.services.frontend.loadbalancer.server.port=3000"
    environment:
      - NEXT_PUBLIC_API_URL=/api # 相对路径，由Traefik转发到后端

前端代码中直接使用fetch('/api/User')即可。

2. Docker用户定义网络 #

若不需要反向代理，手动创建网络让两个独立容器通信：

# 创建共享网络
docker network create app-network
# 启动后端容器并加入网络
docker run -d --name backend --network app-network backend-image
# 启动前端容器并加入网络，配置API地址
docker run -d --name frontend --network app-network -e NEXT_PUBLIC_API_URL=http://backend:8080/api frontend-image

四、独立部署容器的注意事项 #

若分开部署两个容器：

• 确保容器在同一Docker网络（如上述用户定义网络），或后端暴露端口到主机，前端使用主机IP访问。
• 使用环境变量动态配置API地址，避免硬编码，方便在不同环境（开发、测试、生产）切换。

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