getStaticProps

如果从页面导出一个名为 getStaticProps 的函数（静态站点生成），Next.js 将在构建时使用该函数返回的 props 预渲染此页面。

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
}

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

何时使用 getStaticProps？

在以下情况下应使用 getStaticProps：

页面渲染所需数据在用户请求前的构建时即可获取
数据来自无头内容管理系统 (headless CMS)
页面必须预渲染（出于 SEO 考虑）且速度极快 —— getStaticProps 会生成 HTML 和 JSON 文件，两者均可通过 CDN 缓存以提高性能
数据可公开缓存（非用户特定）。在特定情况下可通过中间件重写路径绕过此条件

getStaticProps 何时运行

getStaticProps 始终在服务端运行，从不在客户端运行。您可以使用此工具验证 getStaticProps 内的代码已从客户端包中移除。

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

与增量静态再生 (ISR) 结合使用时，getStaticProps 会在重新验证过期页面的同时在后台运行，并将新页面提供给浏览器。

由于 getStaticProps 生成的是静态 HTML，因此无法访问传入请求（如查询参数或 HTTP 头）。如需访问页面请求，请考虑在 getStaticProps 之外配合使用中间件 (Middleware)。

使用 getStaticProps 从 CMS 获取数据

以下示例展示如何从内容管理系统获取博客文章列表。

// 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 包中，因此可以直接编写数据库查询而无需担心代码泄露到浏览器。

这意味着您无需通过 getStaticProps 获取API 路由（该路由本身从外部源获取数据），而可以直接在 getStaticProps 中编写服务端代码。

参考以下示例。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 路由获取数据，也可以直接在 getStaticProps 中使用 fetch() API 获取数据。

要验证 Next.js 从客户端包中移除了哪些代码，可使用 next-code-elimination 工具。

同时静态生成 HTML 和 JSON

当使用 getStaticProps 的页面在构建时预渲染时，除了页面 HTML 文件外，Next.js 还会生成一个包含 getStaticProps 运行结果的 JSON 文件。

该 JSON 文件将通过 next/link 或 next/router 用于客户端路由。当导航到使用 getStaticProps 预渲染的页面时，Next.js 会获取此 JSON 文件（构建时预计算）并将其用作页面组件的 props。这意味着客户端页面转换不会调用 getStaticProps，因为只使用导出的 JSON。

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

getStaticProps 的使用范围

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

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

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

须知：如果您创建了自定义应用，请确保如链接文档所示将 pageProps 传递给页面组件，否则 props 将为空。

开发环境中的每次请求运行

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

预览模式

您可以使用预览模式 (Preview Mode) 临时绕过静态生成，改为在请求时而非构建时渲染页面。例如，您可能正在使用无头 CMS 并希望在草稿发布前预览它们。

On this page