NNext.js 中文网 GitHub

getStaticProps

getStaticProps 的 API 参考。了解如何使用 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
}

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

context 参数#

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

名称描述
params包含使用动态路由的页面的路由参数。例如,如果页面名为 [id].js,则 params 将类似 { id: ... }。你应将其与 getStaticPaths 一起使用,我们稍后会讲解。
preview(已废弃,改用 draftMode)如果页面处于预览模式,则 preview 为 true,否则为 false。
previewData(已废弃,改用 draftMode)由 setPreviewData 设置的预览数据。
draftMode如果页面处于草稿模式,则 draftMode 为 true,否则为 false。
locale包含当前活动的语言区域(locale)(如果已启用)。
locales包含所有支持的语言区域(locale)(如果已启用)。
defaultLocale包含配置的默认语言区域(locale)(如果已启用)。
revalidateReason提供调用该函数的原因。可能为以下之一:"build"(在构建时运行)、"stale"(重新验证周期已过期,或在开发模式下运行)、"on-demand"(通过按需重新验证触发)

getStaticProps 的返回值#

getStaticProps 函数应返回一个对象,其中包含 props、redirect 或 notFound 之一,后跟一个可选的 revalidate 属性。

props#

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

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

revalidate#

revalidate 属性是以秒为单位的时长,超过该时长后即可重新生成页面(默认为 false,即不进行重新验证)。

js
// 该函数在构建时于服务端被调用。
// 如果启用了重新验证并且有新的请求到来,
// 它可能会在无服务器函数上再次被调用。
export async function getStaticProps() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  return {
    props: {
      posts,
    },
    // Next.js 将尝试重新生成页面:
    // - 当有请求到来时
    // - 最多每 10 秒一次
    revalidate: 10, // 以秒为单位
  }
}

了解更多关于增量静态再生(Incremental Static Regeneration)的信息。

使用 ISR 的页面的缓存状态可以通过读取 x-nextjs-cache 响应头的值来确定。可能的值如下:

  • MISS - 路径不在缓存中(最多发生一次,在首次访问时)
  • STALE - 路径在缓存中,但已超过重新验证时间,因此将在后台更新
  • HIT - 路径在缓存中,且尚未超过重新验证时间

notFound#

notFound 布尔值允许页面返回 404 状态和 404 页面。使用 notFound: true 时,即使之前已成功生成过页面,页面也会返回 404。这旨在支持诸如用户生成的内容被其作者删除之类的用例。注意,notFound 遵循此处所述的相同 revalidate 行为。

js
export async function getStaticProps(context) {
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  if (!data) {
    return {
      notFound: true,
    }
  }

  return {
    props: { data }, // 将作为 props 传递给页面组件
  }
}

小知识:对于 fallback: false 模式,不需要 notFound,因为只有从 getStaticPaths 返回的路径才会被预渲染。

redirect#

redirect 对象允许重定向到内部或外部资源。它应符合 { destination: string, permanent: boolean } 的结构。

在极少数情况下,你可能需要为较旧的 HTTP 客户端指定自定义状态码以正确重定向。在这些情况下,你可以使用 statusCode 属性代替 permanent 属性,但不能同时使用两者。你还可以像 next.config.js 中的重定向那样设置 basePath: false。

js
export async function getStaticProps(context) {
  const res = await fetch(`https://...`)
  const data = await res.json()

  if (!data) {
    return {
      redirect: {
        destination: '/',
        permanent: false,
        // statusCode: 301
      },
    }
  }

  return {
    props: { data }, // 将作为 props 传递给页面组件
  }
}

如果重定向在构建时已知,则应改为在 next.config.js 中添加。

读取文件:使用 process.cwd()#

在 getStaticProps 中可以直接从文件系统读取文件。

为此,你需要获取文件的完整路径。

由于 Next.js 会将你的代码编译到一个单独的目录,你不能使用 __dirname,因为它返回的路径与 Pages Router 不同。

你可以改用 process.cwd(),它会给出 Next.js 正在执行的目录。

jsx
import { promises as fs } from 'fs'
import path from 'path'

// posts 将在构建时由 getStaticProps() 填充
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>
          <h3>{post.filename}</h3>
          <p>{post.content}</p>
        </li>
      ))}
    </ul>
  )
}

// 该函数在构建时于服务端被调用。
// 它不会在客户端被调用,因此你甚至可以直接执行数据库查询。
export async function getStaticProps() {
  const postsDirectory = path.join(process.cwd(), 'posts')
  const filenames = await fs.readdir(postsDirectory)

  const posts = filenames.map(async (filename) => {
    const filePath = path.join(postsDirectory, filename)
    const fileContents = await fs.readFile(filePath, 'utf8')

    // 通常你会在此解析/转换内容
    // 例如,你可以在这里将 markdown 转换为 HTML

    return {
      filename,
      content: fileContents,
    }
  })
  // 通过返回 { props: { posts } },Blog 组件
  // 将在构建时接收到 `posts` 作为 prop
  return {
    props: {
      posts: await Promise.all(posts),
    },
  }
}

export default Blog

版本历史#

版本变更
v13.4.0App Router 现已稳定,并简化了数据获取
v12.2.0按需增量静态再生 已稳定。
v12.1.0新增 按需增量静态再生(beta)。
v10.0.0新增 locale、locales、defaultLocale 和 notFound 选项。
v10.0.0新增 fallback: 'blocking' 返回选项。
v9.5.0稳定的增量静态再生
v9.3.0引入 getStaticProps。
Next.js 中文网