Next.js项目构建时错误API地址致预渲染报错如何解决？

Next.js 构建时预渲染报错，是因为静态生成（SSG）或服务端渲染（SSR）的页面在构建阶段执行数据获取逻辑时，API 请求失败抛出了未捕获的异常，导致构建中断。以下是几种可行的解决方式：

1. 在数据获取函数中捕获错误并返回兜底数据 #

对于使用 getStaticProps 或 getServerSideProps 的页面，用 try/catch 包裹 API 请求逻辑，出错时返回预设的兜底数据，同时传递错误状态给页面组件，而不是让异常冒泡中断构建。

示例代码：

export async function getStaticProps() {
  let data = [];
  let error = null;

  try {
    const res = await fetch('错误的API地址');
    if (!res.ok) throw new Error('API请求返回非成功状态');
    data = await res.json();
  } catch (err) {
    // 捕获所有请求相关错误，设置兜底数据
    error = '数据加载失败，请稍后重试';
    data = [{ id: 0, title: '默认内容' }];
  }

  return {
    props: { data, error },
    // 可选：设置重验证时间，后续请求会重新尝试获取数据
    revalidate: 60,
  };
}

// 页面组件中处理错误状态
export default function Home({ data, error }) {
  if (error) {
    return <div className="error">{error}</div>;
  }

  return (
    <div>
      {data.map(item => (
        <div key={item.id}>{item.title}</div>
      ))}
    </div>
  );
}

2. 切换为客户端侧数据获取（CSR） #

如果你的页面不需要预渲染内容，可以将 API 请求逻辑移到客户端组件中，使用 useEffect 或者数据请求库（如 SWR、React Query）在浏览器端执行请求。这样构建阶段不会执行这些请求，自然不会因 API 错误导致构建失败。

示例代码：

'use client';

import { useEffect, useState } from 'react';

export default function Home() {
  const [data, setData] = useState([]);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const res = await fetch('错误的API地址');
        if (!res.ok) throw new Error('请求失败');
        const fetchedData = await res.json();
        setData(fetchedData);
      } catch (err) {
        setError('数据加载失败');
        // 设置兜底数据
        setData([{ id: 0, title: '默认内容' }]);
      }
    };

    fetchData();
  }, []);

  return (
    <div>
      {error && <div className="error">{error}</div>}
      {data.map(item => (
        <div key={item.id}>{item.title}</div>
      ))}
    </div>
  );
}

3. 对动态路由页面启用 Fallback 模式 #

如果是动态路由页面（如 /posts/[id]），可以在 getStaticPaths 中设置 fallback: true 或 fallback: 'blocking'。开启后，构建阶段只会预渲染你指定的路径，未预渲染的路径会在用户首次访问时动态生成，避免因某个 API 错误导致整个构建失败。

示例代码：

export async function getStaticPaths() {
  // 仅预渲染部分路径，或留空让所有路径动态生成
  return {
    paths: [{ params: { id: '1' } }],
    fallback: true,
  };
}

export async function getStaticProps({ params }) {
  let data = null;
  let error = null;

  try {
    const res = await fetch(`错误的API地址/posts/${params.id}`);
    data = await res.json();
  } catch (err) {
    error = '帖子加载失败';
  }

  return {
    props: { data, error },
    revalidate: 60,
  };
}

4. 兜底方案：忽略构建错误（不推荐优先使用） #

Next.js 12+ 支持在 next.config.js 中配置 ignoreBuildErrors，强制构建完成即使存在预渲染错误。但这会掩盖所有构建阶段的错误，可能隐藏其他代码问题，仅建议作为临时兜底方案。

示例配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  ignoreBuildErrors: true,
};

module.exports = nextConfig;

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