getServerSideProps
当从页面导出一个名为 getServerSideProps
(服务器端渲染)的函数时,Next.js 将使用 getServerSideProps
返回的数据在每次请求时预渲染此页面。如果你想获取经常变化的数据,并希望页面更新以显示最新数据,这将非常有用。
pages/index.tsx
TypeScript
import type { InferGetServerSidePropsType, GetServerSideProps } from 'next'
type Repo = {
name: string
stargazers_count: number
}
export const getServerSideProps = (async () => {
// 从外部 API 获取数据
const res = await fetch('https://api.github.com/repos/vercel/next.js')
const repo: Repo = await res.json()
// 通过 props 将数据传递给页面
return { props: { repo } }
}) satisfies GetServerSideProps<{ repo: Repo }>
export default function Page({
repo,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
return (
<main>
<p>{repo.stargazers_count}</p>
</main>
)
}
你可以在顶层作用域导入模块以在 getServerSideProps
中使用。导入的模块不会被打包到客户端。这意味着你可以直接在 getServerSideProps
中编写服务器端代码,包括从数据库获取数据。
Context 参数
context
参数是一个包含以下键的对象:
名称 | 描述 |
---|---|
params | 如果此页面使用动态路由,params 包含路由参数。如果页面名称是 [id].js ,则 params 将类似于 { id: ... } 。 |
req | HTTP 传入消息对象,带有额外的 cookies 属性,该属性是一个对象,其字符串键映射到 cookie 的字符串值。 |
res | HTTP 响应对象。 |
query | 表示查询字符串的对象,包括动态路由参数。 |
preview | (已弃用,改用 draftMode )如果页面处于预览模式,则为 true ,否则为 false 。 |
previewData | (已弃用,改用 draftMode )由 setPreviewData 设置的预览数据。 |
draftMode | 如果页面处于草稿模式,则为 true ,否则为 false 。 |
resolvedUrl | 请求 URL 的规范化版本,去除了客户端转换的 _next/data 前缀,并包含原始查询值。 |
locale | 包含活动语言环境(如果已启用)。 |
locales | 包含所有支持的语言环境(如果已启用)。 |
defaultLocale | 包含配置的默认语言环境(如果已启用)。 |
getServerSideProps 返回值
getServerSideProps
函数应返回一个包含以下任一属性的对象:
props
props
对象是键值对,每个值都由页面组件接收。它应该是一个可序列化的对象,以便可以使用 JSON.stringify
序列化所有传递的 props。
export async function getServerSideProps(context) {
return {
props: { message: `Next.js 非常棒` }, // 将作为 props 传递给页面组件
}
}
notFound
notFound
布尔值允许页面返回 404
状态和 404 页面。使用 notFound: true
,即使之前成功生成了页面,页面也将返回 404
。这旨在支持用户生成的内容被作者删除等用例。
export async function getServerSideProps(context) {
const res = await fetch(`https://.../data`)
const data = await res.json()
if (!data) {
return {
notFound: true,
}
}
return {
props: { data }, // 将作为 props 传递给页面组件
}
}
redirect
redirect
对象允许重定向到内部和外部资源。它应该匹配 { destination: string, permanent: boolean }
的形式。在某些罕见情况下,你可能需要为旧的 HTTP
客户端分配自定义状态码以正确重定向。在这些情况下,你可以使用 statusCode
属性而不是 permanent
属性,但不能同时使用。
export async function getServerSideProps(context) {
const res = await fetch(`https://.../data`)
const data = await res.json()
if (!data) {
return {
redirect: {
destination: '/',
permanent: false,
},
}
}
return {
props: {}, // 将作为 props 传递给页面组件
}
}
版本历史
版本 | 变更 |
---|---|
v13.4.0 | App Router 现已稳定,数据获取简化 |
v10.0.0 | 添加 locale 、locales 、defaultLocale 和 notFound 选项 |
v9.3.0 | 引入 getServerSideProps |