NNext.js 中文网 GitHub

getStaticProps

使用 getStaticProps 获取数据并生成静态页面。了解更多关于 Next.js 中用于数据获取的这个 API 的信息。

如果你从某个页面 export 一个名为 getStaticProps 的函数(静态站点生成),Next.js 将在构建时使用 getStaticProps 返回的 props 预渲染该页面。

pages/index.tsx
import type { InferGetStaticPropsType, GetStaticProps } from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}
pages/index.js
export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

请注意,无论渲染类型如何,任何 props 都会传递给页面组件,并可在初始 HTML 的客户端查看。这是为了让页面能够正确 hydrate(水合)。请确保不要在 props 中传递任何不应在客户端可用的敏感信息。

getStaticProps API 参考涵盖了可与 getStaticProps 一起使用的所有参数和 props。

什么时候应该使用 getStaticProps?#

在以下情况下应使用 getStaticProps:

  • 渲染页面所需的数据在构建时即可获得,早于用户的请求
  • 数据来自无头 CMS
  • 页面必须预渲染(出于 SEO 考虑)且速度非常快 —— getStaticProps 会生成 HTML 和 JSON 文件,两者都可以被 CDN 缓存以提升性能
  • 数据可以公开缓存(非用户特定)。在某些特定情况下,可以通过使用 Proxy 重写路径来绕过此条件。

getStaticProps 何时运行#

getStaticProps 始终在服务器上运行,从不在客户端运行。你可以使用此工具验证 getStaticProps 内编写的代码是否已从客户端 bundle 中移除。

  • getStaticProps 始终在 next build 期间运行
  • 使用 fallback: true 时,getStaticProps 在后台运行
  • 使用 fallback: blocking 时,getStaticProps 在初始渲染之前被调用
  • 使用 revalidate 时,getStaticProps 在后台运行
  • 使用 revalidate() 时,getStaticProps 按需在后台运行

与增量静态再生结合使用时,getStaticProps 将在后台运行,同时对旧页面进行重新验证,并将新页面提供给浏览器。

getStaticProps 无法访问传入的请求(例如查询参数或 HTTP 标头),因为它生成的是静态 HTML。如果你的页面需要访问请求,请考虑在 getStaticProps 之外使用 Proxy。

使用 getStaticProps 从 CMS 获取数据#

以下示例展示了如何从 CMS 获取博客文章列表。

pages/blog.tsx
// posts 将在构建时由 getStaticProps() 填充
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// 此函数在构建时于服务器端被调用。
// 它不会在客户端被调用,因此你甚至可以
// 直接进行数据库查询。
export async function getStaticProps() {
  // 调用外部 API 端点以获取文章。
  // 你可以使用任何数据获取库
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // 通过返回 { props: { posts } },Blog 组件
  // 将在构建时收到 `posts` 作为 prop
  return {
    props: {
      posts,
    },
  }
}
pages/blog.js
// posts 将在构建时由 getStaticProps() 填充
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// 此函数在构建时于服务器端被调用。
// 它不会在客户端被调用,因此你甚至可以
// 直接进行数据库查询。
export async function getStaticProps() {
  // 调用外部 API 端点以获取文章。
  // 你可以使用任何数据获取库
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // 通过返回 { props: { posts } },Blog 组件
  // 将在构建时收到 `posts` 作为 prop
  return {
    props: {
      posts,
    },
  }
}

getStaticProps API 参考涵盖了可与 getStaticProps 一起使用的所有参数和 props。

直接编写服务端代码#

由于 getStaticProps 只在服务器端运行,它从不会在客户端运行。它甚至不会被包含在供浏览器使用的 JS bundle 中,因此你可以直接编写数据库查询,而无需担心它们被发送到浏览器。

这意味着,你可以在 getStaticProps 中直接编写服务端代码,而不必从 getStaticProps 中获取 API 路由(该路由本身从外部来源获取数据)。

来看下面的例子。使用一个 API 路由从 CMS 获取一些数据,然后直接从 getStaticProps 调用该 API 路由。这会产生一次额外的调用,降低性能。相反,可以通过使用 lib/ 目录来共享从 CMS 获取数据的逻辑,然后将其与 getStaticProps 共享。

lib/load-posts.js
// 以下函数被共享
// 供 getStaticProps 和 API 路由使用
// 来自 `lib/` 目录
export async function loadPosts() {
  // 调用外部 API 端点以获取文章
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}
pages/blog.js
// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// 此函数只在服务器端运行
export async function getStaticProps() {
  // 不必请求 `/api` 路由,你可以
  // 直接在 `getStaticProps` 中调用相同的函数
  const posts = await loadPosts()

  // 返回的 Props 将传递给页面组件
  return { props: { posts } }
}

或者,如果你没有使用 API 路由来获取数据,那么 fetch() API 可以 直接在 getStaticProps 中使用来获取数据。

要验证 Next.js 从客户端 bundle 中移除了哪些内容,你可以使用 next-code-elimination 工具。

同时静态生成 HTML 和 JSON#

当带有 getStaticProps 的页面在构建时被预渲染时,除了页面 HTML 文件外,Next.js 还会生成一个 JSON 文件,用于保存运行 getStaticProps 的结果。

该 JSON 文件将用于通过 next/link 或 next/router 进行的客户端路由。当你导航到使用 getStaticProps 预渲染的页面时,Next.js 会获取这个 JSON 文件(在构建时预先计算)并将其用作页面组件的 props。这意味着客户端页面切换 不会 调用 getStaticProps,因为只使用导出的 JSON。

使用增量静态生成时,getStaticProps 将在后台执行,以生成客户端导航所需的 JSON。你可能会看到对同一页面发出多个请求,但这是预期行为,对最终用户性能没有影响。

在哪里可以使用 getStaticProps#

getStaticProps 只能从页面中 export。你不能从非页面文件、_app、_document 或 _error 中导出它。

这一限制的原因之一是 React 需要在页面渲染之前获得所有必需的数据。

此外,你必须将 getStaticProps 作为独立函数导出 —— 如果将 getStaticProps 添加为页面组件的属性,它将 无法 工作。

小知识: 如果你创建了自定义 app,请确保按照链接文档中的方式将 pageProps 传递给页面组件,否则 props 将为空。

在开发环境中每次请求都会运行#

在开发环境中(next dev),getStaticProps 会在每次请求时被调用。

预览模式#

你可以使用 预览模式 临时绕过静态生成,在请求时而非构建时渲染页面。例如,你可能正在使用无头 CMS,希望在草稿发布前对其进行预览。

Next.js 中文网