Next.js项目部署与本地Build报错：根路径预渲染失败

这个错误的核心原因是：getStaticProps中尝试解析JSON，但实际拿到的是HTML内容（比如404错误页、500错误页的源码，开头都是<）。以下是针对性的排查和解决步骤：

1. 先确认请求返回的内容 #

在getStaticProps里临时添加代码，打印请求的响应文本，明确返回的是不是JSON：

export async function getStaticProps() {
  const res = await fetch('你的API地址');
  // 先打印响应内容，排查是否为HTML
  const responseText = await res.text();
  console.log('API响应内容:', responseText);
  
  // 再尝试解析JSON（如果是HTML会报错，此时看控制台输出即可）
  const data = JSON.parse(responseText);
  return { props: { data } };
}

执行npm run build，看控制台输出的responseText：如果是HTML，说明API请求路径错误、API本身返回错误页，或者环境配置有问题。

2. 验证API端点的有效性 #

直接在浏览器/Postman中访问你的API地址，确认返回的是标准JSON：

• 如果返回HTML，检查API路由的代码：有没有语法错误？有没有正确设置res.status(200).json(xxx)？有没有拼写错误的路径？
• 如果是外部API，确认构建环境能正常访问该API（比如防火墙限制、域名解析问题）。

3. 内部API路由避免用HTTP请求 #

如果调用的是Next.js自身的pages/api下的路由，不要用fetch请求，直接导入API的处理函数：

// 示例：pages/api/posts.js
export async function fetchPosts() {
  // 这里写实际获取数据的逻辑（比如读数据库、文件）
  return [{ id: 1, title: "测试文章" }];
}

export default async function handler(req, res) {
  const posts = await fetchPosts();
  res.status(200).json(posts);
}

然后在页面的getStaticProps中直接调用函数：

import { fetchPosts } from '../api/posts';

export async function getStaticProps() {
  const data = await fetchPosts();
  return { props: { data } };
}

这种方式跳过HTTP请求，彻底避免路径、响应格式等问题。

4. 强制检查响应状态 #

在fetch后添加状态校验，避免解析错误响应的HTML：

export async function getStaticProps() {
  const res = await fetch('你的API地址');
  // 响应状态码非2xx时直接抛出错误
  if (!res.ok) {
    throw new Error(`API请求失败，状态码: ${res.status}`);
  }
  const data = await res.json();
  return { props: { data } };
}

5. 检查部署环境的路径配置 #

如果部署时设置了basePath（比如部署在子路径下），确保API请求路径包含该前缀：

// next.config.js
module.exports = {
  basePath: '/my-project',
};

请求时用绝对路径或拼接前缀：

const apiUrl = `${process.env.NEXT_PUBLIC_BASE_PATH}/api/data`;
const res = await fetch(apiUrl);

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