Docker化前端连接后端时出现Failed to Fetch Error问题排查

核心原因 #

你的问题本质是Docker网络环境下，客户端（浏览器）与服务器端（前端Node进程）的网络访问逻辑不一致：

• 前端的/api/...路由能正常工作，是因为这些路由在前端的服务器进程（比如Next.js的Node服务）中执行，属于Docker内部网络，能直接通过backend这个服务名访问后端容器。
• 而直接发起的请求（比如useSWR的客户端请求、或你以为是服务器端但实际在客户端执行的请求）是由浏览器发起的，浏览器处于Docker外部网络，无法识别backend这个Docker内部服务名，导致请求失败。

另外，你的getBoardDetailsData函数虽然标注了server-only，但如果在客户端组件中调用，Next.js可能会尝试在客户端执行（即使有server-only约束，也可能因动态渲染逻辑触发客户端执行），同样会遇到浏览器无法解析backend的问题。

解决思路 #

1. 统一通过前端API路由做代理（推荐） #

不管是客户端还是服务器端的请求，都先请求前端的/api路由，再由/api路由转发到后端，彻底避免跨域和网络解析问题：

• 修改客户端请求地址为相对路径：

  const { data, error, isLoading } = useSWR<PaginatedBoardsResponse>(
    `/api/boards?tab=${activeTab}&page=${currentPage}&limit=${perPage}`,
    fetchBoards(accessToken as string),
    {
      revalidateOnFocus: true,
      keepPreviousData: true,
      revalidateIfStale: true,
    }
  );
  

• 创建前端API路由（比如/app/api/boards/route.ts），在其中转发请求到后端：

  import { NextRequest, NextResponse } from 'next/server';
  
  export async function GET(request: NextRequest) {
    const searchParams = request.nextUrl.searchParams;
    const backendUrl = `http://backend:5000/boards?${searchParams.toString()}`;
    const accessToken = request.headers.get('Authorization');
  
    const response = await fetch(backendUrl, {
      headers: {
        Authorization: accessToken || '',
        'Content-Type': 'application/json',
      },
    });
  
    const data = await response.json();
    return NextResponse.json(data, { status: response.status });
  }
  

• 对于getBoardDetailsData，同样修改请求地址为/api/boards/${boardId}/details，对应创建/app/api/boards/[boardId]/details/route.ts做转发。

2. 区分服务器端与客户端的请求地址 #

如果不想用API路由代理，可以分别配置不同环境的请求地址：

• 服务器端（比如getBoardDetailsData）：保留http://backend:5000作为基础地址，因为在Docker内部网络中可以直接访问。
• 客户端：使用相对路径（比如/boards/...），然后在前端框架中配置路由重写。以Next.js为例，在next.config.js中添加：

  module.exports = {
    async rewrites() {
      return [
        {
          source: '/boards/:path*',
          destination: 'http://backend:5000/boards/:path*',
        },
      ];
    },
  };
  

  这样浏览器请求/boards/xxx时，会被Next.js服务器转发到后端，避免浏览器直接访问backend服务名。

3. 修正客户端环境变量（不推荐） #

如果一定要用绝对地址，需要确保客户端能获取到正确的主机名：

• 将环境变量名改为NEXT_PUBLIC_SERVER_HOST（Next.js中只有前缀为NEXT_PUBLIC_的变量会暴露给客户端），并设置为前端的外部访问地址（比如localhost:3000），然后通过前端代理转发到后端。但这种方式需要额外配置代理，不如前两种方案简洁。

验证步骤 #

1. 打开浏览器开发者工具的Network面板，查看失败请求的地址：如果请求地址是http://backend:5000/...，则确认是浏览器无法解析Docker服务名导致的问题。
2. 检查后端容器的日志，确认是否收到请求：如果服务器端的请求（比如getBoardDetailsData）能到达后端，而客户端请求不能，说明是客户端网络解析的问题。

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