Next.js的getStaticProps是静态站点生成（SSG）模式下的核心数据获取方法，它会在构建阶段运行，获取到的数据会作为页面的props传递给对应的页面组件，很多开发者在使用时容易因为格式或逻辑问题导致数据无法正确传递。
getStaticProps的基本工作规则
getStaticProps只能导出在页面组件文件（pages目录下的文件）中，不能在组件文件或者非页面文件中使用。它的返回值必须是一个对象，且对象中必须包含props属性，这个props属性的值就是最终要传递给页面组件的数据。
一个最基础的getStaticProps写法如下：
export async function getStaticProps() {
// 模拟获取数据
const data = await fetch('https://ipipp.com/api/posts').then(res => res.json());
return {
props: {
posts: data
}
};
}
确保数据正确传递的核心要点
1. 返回值格式必须严格符合要求
getStaticProps的返回值除了props之外，还可以包含revalidate（增量静态再生成的重新验证时间，单位秒）和notFound（布尔值，控制是否返回404页面），但props是传递数据到组件的必填项。
如果返回值中没有props，或者props的值不是对象，页面组件就无法接收到对应的数据。比如下面的错误写法会导致数据传递失败：
// 错误示例1：缺少props属性
export async function getStaticProps() {
return {
data: {
title: '测试标题'
}
};
}
// 错误示例2：props的值不是对象
export async function getStaticProps() {
return {
props: '直接返回字符串'
};
}
2. 页面组件必须接收对应的props
getStaticProps传递的props会被直接作为页面组件的第一参数传入，因此页面组件需要定义对应的参数来接收数据。如果组件没有定义接收参数，或者参数名和传递的props属性不匹配，也无法正确拿到数据。
正确的页面组件接收方式：
// 页面组件接收getStaticProps传递的props
export default function PostsPage({ posts }) {
return (
<div>
<h1>文章列表</h1>
<ul>
{posts.map(post => (
<li key={post.id}>{post.title}</li>
))}
</ul>
</div>
);
}
// 对应的getStaticProps
export async function getStaticProps() {
const res = await fetch('https://ipipp.com/api/posts');
const posts = await res.json();
return {
props: {
posts
}
};
}
3. 处理数据获取失败的场景
如果getStaticProps内部的数据获取过程出错，没有正确处理错误的话，可能会导致构建失败，或者返回不完整的props。建议在getStaticProps内部添加错误处理，比如数据获取失败时返回默认数据，或者设置notFound: true返回404页面。
export async function getStaticProps() {
try {
const res = await fetch('https://ipipp.com/api/posts');
if (!res.ok) {
throw new Error('数据获取失败');
}
const posts = await res.json();
return {
props: {
posts
},
revalidate: 60 // 每60秒重新验证一次数据
};
} catch (error) {
// 数据获取失败时返回空数组，避免页面报错
return {
props: {
posts: []
}
};
}
}
常见数据传递问题排查
- 检查getStaticProps是否在页面文件中导出，且是默认导出或者命名导出正确
- 检查getStaticProps的返回值是否包含
props属性，且props是对象类型 - 检查页面组件的参数是否和
props中的属性名一致，避免解构赋值时的名称错误 - 如果使用了增量静态再生成，检查
revalidate的值是否合理，避免数据更新不及时 - 检查数据获取接口是否可访问，避免因为接口报错导致没有返回有效的props数据
注意事项
getStaticProps只在构建阶段或者增量静态再生成阶段运行，不会在客户端运行，因此如果在getStaticProps中使用了浏览器特有的API（比如window、document），会导致运行报错。同时传递给props的数据必须是可序列化的，因为Next.js会把props序列化为JSON字符串，如果函数、Date对象等不可序列化的内容作为props传递，也会被处理成对应的序列化结果，可能导致数据不符合预期。
Next.jsgetStaticProps静态生成数据传递页面组件修改时间：2026-07-23 12:15:16