如何解决Next.js服务端组件构建时调用Spring Boot API的fetch失败错误

你遇到的TypeError: fetch failed本质是Next.js默认的**静态预渲染（Static Rendering）机制导致的：在next build阶段，服务端组件的代码会被执行以生成静态HTML，而CI环境无法访问内部Spring Boot API，因此触发请求失败。解决核心是让数据拉取延迟到运行时（Runtime）**执行，避免构建阶段触发API调用。

以下几种方案都是官方推荐的规范模式，你计划用<Suspense>包裹独立组件的思路完全可行，具体实现如下：

1. 强制动态渲染（全局/页面级） #

通过配置标记页面为动态渲染，Next.js会跳过构建时预渲染，仅在用户请求时在服务器端执行组件逻辑：

• 页面级配置：在page.tsx顶部添加动态渲染声明

// app/page.tsx
export const dynamic = 'force-dynamic'; // 强制页面每次请求都在服务器端运行

export default async function Page() {
  // 此处的fetch会在运行时执行，构建阶段不会触发
  const res = await fetch(process.env.SPRING_BOOT_API_URL, { cache: 'no-store' });
  const data = await res.json();
  return <div>{data.content}</div>;
}

• 全局配置：如果所有页面都需要动态渲染，可在next.config.js中设置

/** @type {import('next').NextConfig} */
const nextConfig = {
  dynamic: 'force-dynamic',
  output: 'standalone', // 适配Docker部署的推荐配置
};

module.exports = nextConfig;

2. 用动态函数触发运行时执行 #

Next.js会自动识别组件中使用的动态函数（如cookies()、headers()、unstable_noStore()），并将组件标记为动态渲染，构建阶段不会执行其代码：

import { unstable_noStore as noStore } from 'next/cache';

export default async function Page() {
  noStore(); // 强制组件在运行时执行，跳过构建预渲染
  const res = await fetch(process.env.SPRING_BOOT_API_URL);
  const data = await res.json();
  return <div>{data.content}</div>;
}

3. <Suspense>包裹独立数据组件（推荐） #

将数据拉取逻辑封装到独立服务端组件，用<Suspense>包裹实现局部加载状态，同时确保数据拉取仅在运行时执行：

// app/components/ServerData.tsx
import { unstable_noStore as noStore } from 'next/cache';

export default async function ServerData() {
  noStore();
  const res = await fetch(process.env.SPRING_BOOT_API_URL);
  if (!res.ok) throw new Error('API请求失败');
  const data = await res.json();
  return <div>{data.content}</div>;
}

// app/page.tsx
import { Suspense } from 'react';
import ServerData from './components/ServerData';

export default function Page() {
  return (
    <div>
      <h1>主页</h1>
      <Suspense fallback={<div>加载中...</div>}>
        <ServerData />
      </Suspense>
    </div>
  );
}

这种模式既符合组件拆分的最佳实践，又能隔离数据拉取逻辑，同时<Suspense>的使用是官方明确推荐的服务端组件加载状态处理方案。

1. 组件内局部错误捕获 #

在数据拉取组件中添加try/catch，处理API请求失败的情况：

// app/components/ServerData.tsx
import { unstable_noStore as noStore } from 'next/cache';

export default async function ServerData() {
  noStore();
  let data = null;
  let errorMsg = '';

  try {
    const res = await fetch(process.env.SPRING_BOOT_API_URL);
    if (!res.ok) throw new Error(`API返回状态码：${res.status}`);
    data = await res.json();
  } catch (err) {
    errorMsg = err instanceof Error ? err.message : '未知错误';
  }

  if (errorMsg) return <div className="text-red-500">加载失败：{errorMsg}</div>;
  return <div>{data?.content}</div>;
}

2. 全局/局部错误边界 #

通过error.tsx定义错误边界，当服务端组件抛出错误时，自动展示友好提示：

• 全局错误边界（app/error.tsx）：

'use client'; // 错误边界必须是客户端组件

export default function Error({ error, reset }) {
  return (
    <div className="p-8 text-center">
      <h2>页面加载出错</h2>
      <p>{error.message}</p>
      <button onClick={reset} className="mt-4 px-4 py-2 bg-blue-500 text-white rounded">
        重试
      </button>
    </div>
  );
}

• 局部错误边界：在数据组件的同级目录创建error.tsx，仅处理该组件的错误：

// app/components/error.tsx
'use client';

export default function Error({ error, reset }) {
  return (
    <div className="p-4 bg-red-100 rounded">
      <p>数据加载失败：{error.message}</p>
      <button onClick={reset} className="mt-2 px-3 py-1 bg-blue-500 text-white rounded">
        重新加载
      </button>
    </div>
  );
}

1. CI环境模拟数据 #

如果必须在构建阶段保留部分静态内容，可通过环境变量判断CI环境，返回模拟数据：

// app/components/ServerData.tsx
import { unstable_noStore as noStore } from 'next/cache';

export default async function ServerData() {
  // CI构建时返回模拟数据
  if (process.env.NEXT_PUBLIC_BUILD_ENV === 'ci') {
    return <div>CI构建模拟数据</div>;
  }

  noStore();
  const res = await fetch(process.env.SPRING_BOOT_API_URL);
  const data = await res.json();
  return <div>{data.content}</div>;
}

在GitHub Action的构建步骤中设置环境变量：

- name: 构建Next.js应用
  env:
    NEXT_PUBLIC_BUILD_ENV: ci
    SPRING_BOOT_API_URL: ${{ secrets.SPRING_BOOT_API_URL }}
  run: npm run build

2. 禁用不必要的预渲染检查 #

在next.config.js中关闭构建时的预渲染错误检查（仅在确认运行时数据拉取逻辑正确后使用）：

const nextConfig = {
  output: 'standalone',
  typescript: {
    ignoreBuildErrors: false, // 保留TypeScript检查
  },
  eslint: {
    ignoreDuringBuilds: false, // 保留ESLint检查
  },
};

module.exports = nextConfig;

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