字
字节笔记本
2026年2月22日
解决 Next.js 预渲染错误：Error occurred prerendering page '/'
本文介绍如何解决 Next.js 项目中常见的 "Error occurred prerendering page '/'" 错误，帮助开发者快速定位和修复预渲染问题。
错误概述
在构建 Next.js 应用时，你可能会遇到以下错误信息：
Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-error
这个错误表示 Next.js 在静态生成（SSG）页面时失败了。由于 Next.js 默认会尝试预渲染所有页面，任何在构建时执行的代码出现问题都会导致此错误。
常见原因
1. 使用了浏览器专属 API
在预渲染期间，代码在 Node.js 环境中运行，无法访问 window、document 等浏览器对象。
错误示例：
javascript
// pages/index.js
export default function Home() {
// ❌ 这会报错，因为构建时没有 window 对象
const width = window.innerWidth;
return <div>Width: {width}</div>;
}解决方案：
javascript
import { useEffect, useState } from 'react';
export default function Home() {
const [width, setWidth] = useState(0);
useEffect(() => {
// ✅ 在客户端执行
setWidth(window.innerWidth);
}, []);
return <div>Width: {width}</div>;
}2. 数据获取失败
使用 getStaticProps 或 getServerSideProps 时，API 请求失败会导致预渲染错误。
错误示例：
javascript
export async function getStaticProps() {
// ❌ 如果 API 失败，构建会中断
const res = await fetch('https://api.example.com/data');
const data = await res.json();
return { props: { data } };
}解决方案：
javascript
export async function getStaticProps() {
try {
const res = await fetch('https://api.example.com/data');
if (!res.ok) {
throw new Error(`HTTP error! status: ${res.status}`);
}
const data = await res.json();
return { props: { data } };
} catch (error) {
console.error('Failed to fetch data:', error);
// 返回空数据或默认值，让构建继续
return {
props: {
data: [],
error: 'Failed to load data'
}
};
}
}3. 动态路由参数缺失
使用 getStaticPaths 时，如果返回的 paths 数组为空或格式不正确，会导致预渲染失败。
错误示例：
javascript
export async function getStaticPaths() {
// ❌ 返回空数组会导致所有动态路由 404
return {
paths: [],
fallback: false
};
}解决方案：
javascript
export async function getStaticPaths() {
const posts = await fetchPosts();
const paths = posts.map((post) => ({
params: { id: post.id.toString() },
}));
return {
paths,
fallback: 'blocking' // 或 true，允许增量静态生成
};
}4. 环境变量缺失
构建时依赖的环境变量未设置，导致代码执行失败。
检查方法：
javascript
// 确保必需的环境变量已设置
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('API_KEY environment variable is required');
}解决方案：
- 在
.env.local或 CI/CD 环境中设置所有必需的环境变量 - 使用默认值处理可选变量
调试技巧
1. 查看完整错误堆栈
运行构建命令时添加更多日志：
bash
next build 2>&1 | tee build.log2. 使用 development 模式测试
bash
npm run dev在开发模式下，错误信息通常更详细。
3. 逐步排查
- 注释掉页面中的部分代码
- 重新构建
- 定位具体出错的代码行
4. 禁用预渲染（临时方案）
如果某个页面确实无法在构建时渲染，可以禁用静态生成：
javascript
export async function getStaticProps() {
return {
props: {},
// 启用 ISR，每 1 秒重新验证
revalidate: 1
};
}或使用客户端数据获取：
javascript
import useSWR from 'swr';
export default function Page() {
const { data, error } = useSWR('/api/data', fetcher);
if (error) return <div>Failed to load</div>;
if (!data) return <div>Loading...</div>;
return <div>{data.title}</div>;
}最佳实践
- 分离服务端和客户端代码：使用
useEffect处理浏览器 API - 添加错误边界：使用 React Error Boundary 捕获渲染错误
- 验证外部数据：始终检查 API 响应状态
- 使用 TypeScript：类型检查可以在构建前发现潜在问题
- 渐进式采用 SSG：对复杂页面先使用 SSR，再优化为 SSG
相关资源
分享: