NNext.js 中文网 GitHub

getServerSideProps

getServerSideProps 的 API 参考。了解如何使用 Next.js 在每次请求时获取数据。

当从页面导出名为 getServerSideProps(服务端渲染)的函数时,Next.js 会在每次请求时使用 getServerSideProps 返回的数据预渲染此页面。如果你想获取经常变化的数据,并让页面更新以显示最新数据,这很有用。

pages/index.tsx
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>
  )
}
pages/index.js
export async function getServerSideProps() {
  // 从外部 API 获取数据
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  // 通过 props 将数据传递给页面
  return { props: { repo } }
}

export default function Page({ repo }) {
  return (
    <main>
      <p>{repo.stargazers_count}</p>
    </main>
  )
}

你可以在顶层作用域导入模块以供 getServerSideProps 使用。所使用的导入不会被打包到客户端。这意味着你可以直接在 getServerSideProps 中编写服务端代码,包括从数据库获取数据。

context 参数#

context 参数是一个包含以下键的对象:

名称描述
params如果此页面使用动态路由,params 包含路由参数。如果页面名为 [id].js,则 params 将形如 { id: ... }。
reqHTTP IncomingMessage 对象,带有一个额外的 cookies 属性,该对象以字符串键映射到 cookie 的字符串值。
resHTTP 响应对象。
query表示查询字符串的对象,包括动态路由参数。
preview(已废弃,改用 draftMode)如果页面处于 Preview Mode 模式,preview 为 true,否则为 false。
previewData(已废弃,改用 draftMode)由 setPreviewData 设置的预览数据。
draftMode如果页面处于 Draft Mode,draftMode 为 true,否则为 false。
resolvedUrl请求 URL 的标准化版本,会去除用于客户端切换的 _next/data 前缀,并包含原始的查询值。
locale包含当前启用的区域设置(如果已启用)。
locales包含所有支持的区域设置(如果已启用)。
defaultLocale包含配置的默认区域设置(如果已启用)。

getServerSideProps 的返回值#

getServerSideProps 函数应返回一个包含以下任意一项属性的对象:

props#

props 对象是一个键值对,每个值都会被页面组件接收。它应该是一个可序列化的对象,以便传递的任何 props 都能用 JSON.stringify 序列化。

jsx
export async function getServerSideProps(context) {
  return {
    props: { message: `Next.js is awesome` }, // 将作为 props 传递给页面组件
  }
}

notFound#

notFound 布尔值允许页面返回 404 状态和 404 页面。使用 notFound: true 时,即使之前成功生成过页面,页面也会返回 404。这是为了支持诸如用户生成的内容被其作者删除之类的用例。

js
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 属性,但不能同时使用两者。

js
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.0App Router 现已稳定,并简化了数据获取
v10.0.0新增了 locale、locales、defaultLocale 和 notFound 选项。
v9.3.0引入了 getServerSideProps。
Next.js 中文网