Blitz 尚在 beat 阶段! 🎉 预计会在今年的 Q3 季度发布 1.0
Back to Documentation Menu

getServerSideProps API

Topics

Jump to a Topic

如果你从一个页面中导出一个成为 getServerSidePropsasync 函数, Blitz 将会通过 getServerSideProps 返回的数据在每个请求上预渲染此 页面。

export async function getServerSideProps(context) {
  return {
    props: {}, // 将会以 props 形式传递给页面组件
  }
}

context 参数是一个拥有如下键的对象:

  • params:如果这个页面使用动态路由,params 包含这个路由参数。如果页面 名字是 [id].js,那么 params 将会像 { id: ... }。想要了解更多请查 阅动态路由文档
  • reqHTTP IncomingMessage 对象
  • resHTTP response 对象
  • query:请求字符串。
  • preview:如果这个页面是预览模式则 previewtrue,否则为 false。请查阅预览模式文档
  • previewData:通过 setPreviewData 设置的预览数据。请查 阅预览模式文档
  • resolveUrl:请求 URL 的规范化版本,可为客户端转换去除 _next/data 前 缀,并包括了原始的查询值。
  • locale 包含目前激活的 locale 配置(如果已开启)。
  • locales 包含所有支持的 locales(如果已开启)。
  • defaultLocale 包含配置后的默认 local(如果已开启)。

getServerSideProps 应该返回包含如下的对象:

  • props——一个必须的对象,其值将会被页面组件获取到。必须 是可序列化

  • notFound——一个可选的布尔值,允许页面返回一个 404 状态及页面。下方 是如何使用的示例:

    export async function getServerSideProps(context) {
      const data = /* ... */
    
      if (!data) {
        return {
          notFound: true,
        }
      }
    
      return {
        props: {}, // 将会以 props 形式传递给页面组件
      }
    }
  • redirect——一个可选的对象,允许重定向到内部或外部资源。格式需要匹配 { destination: string, permanent: boolean }。在某些罕见的场景中,你可 能会需要用来将一个自定义的状态码给一个老的 HTTP 客户端以正确地重定向。在 这时,你可以使用 statusCode 属性而非 permanent 属性,但不要同时使用 两者。下方是如何使用的示例:

    export async function getServerSideProps(context) {
      const data = /* ... */
    
      if (!data) {
        return {
          redirect: {
            destination: "/",
            permanent: false,
          },
        }
      }
    
      return {
        props: {}, // 将会以 props 形式传递给页面组件
      }
    }

注意:你可以在顶层作用域来导入模块,以供在 getStaticProps 中使用。 在 getStaticProps 中使用的导入将不捆绑在客户端中。

这意味着你可以getStaticProps 中直接编写服务端代码。包括从文件系 统或数据库中的读取操作。

简单示例

这是一个有关如何使用 getServerSideProps 在请求时获取数据并进行预渲染的示 例。

function Page({data}) {
  // 渲染数据...
}

// 该函数在每一次请求中都会被调用
export async function getServerSideProps() {
  const data = /* ... */

  // 通过 props 来将数据传递给页面
  return {props: {data}}
}

export default Page

我该何时使用 getServerSideProps?

当你需要预渲染一个必须预先在请求过程中获取到数据的页面时,可以使用 getServerSideProps。浏览器接收第一个字节的时间(TTFB)将会被 getStaticProps 慢,因为服务器必须在每次请求来时计算结果,且结果无法在没 有额外配置的时候被 CDN 缓存。

如果你不需要预渲染数据,你应该考虑在客户端获取数据 。点击这里查看更多

TypeScript:使用 GetServerSideProps

对于 TypeScript,你可以从 blitz 中使用 GetServerSideProps 类型:

import { GetServerSideProps } from "blitz"

export const getServerSideProps: GetServerSideProps = async (context) => {
  // ...
}

如果你想要为你的 props 获取推断的类型,你可以使用 InferGetServerSidePropsType<typeof getServerSideProps>,像这样:

import { InferGetServerSidePropsType } from 'blitz'

type Data = { ... }

export const getServerSideProps = async () => {
  const data: Data = /* ... */

  return {
    props: {
      data,
    },
  }
}

function Page({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {
  // 将推断 posts 为 Data 类
}

export default Page

技术细节

仅在服务端支持

getServerSideProps 仅在服务端运行并且永远不会在浏览器上运行。如果一个页 面使用 getServerSideProps,那么:

  • 当你直接请求这个页面,getServerSideProps 将在请求过程中执行,且这个页 面将会通过返回的 props 来预渲染。
  • 当你通过客户端页面 <Link>router文档)过渡时请 求这个页面,Blitz 会发送一个 API 请求到服务器上,来执行 getServerSideProps。它将返回包括执行 getServerSideProps 结果的 JSON,并且这个 JSON 将会被用来渲染这个页面。所有这些工作将会自动被 Blitz 执行,所以你只要在 getServerSideProps 定义后不需要做任何额外的工作。

你可以使用这个工具 来验证 Blitz 从客户端打包后删除的内容。

你可以使用

仅在页面中支持

getServerSideProps 仅能在一个页面中被导出。你无法在一个非页面 文件中导出。

同时,你必须使用 export async function getServerSideProps() {}——如果你 将getServerSideProps作为一个页面组件的属性,它将无法正常工作。

首屏渲染的用户体验

尽管带有 getServerSideProps 的页面将会在服务端上被预渲染,但如果你的页面 包含着初始页面需要但缺失的属性的查询,则回退到页面正在加载的状态。当查询到 的数据加载到应用中时,由于页面内容会快速更改,从而导致产生闪烁的意外效果。

点击这里 来探索改善你的页面在首屏渲染时的用户体 验(UX)的方法。


Idea for improving this page? Edit it on GitHub.