NNext.js 中文网 GitHub

getStaticPaths

getStaticPaths 的 API 参考。了解如何使用 getStaticPaths 获取数据并生成静态页面。

当从使用动态路由的页面中导出一个名为 getStaticPaths 的函数时,Next.js 将静态预渲染 getStaticPaths 指定的所有路径。

pages/repo/[name].tsx
import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 请参阅下面的 "paths" 部分
    ],
    fallback: true, // false 或 "blocking"
  }
}) satisfies GetStaticPaths

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/repo/[name].js
export async function getStaticPaths() {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 请参阅下面的 "paths" 部分
    ],
    fallback: true, // false 或 "blocking"
  }
}

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
}

getStaticPaths 返回值#

getStaticPaths 函数应返回一个包含以下必需属性的对象:

paths#

paths 键决定哪些路径将被预渲染。例如,假设你有一个使用动态路由的页面,名为 pages/posts/[id].js。如果你从这个页面导出 getStaticPaths 并为 paths 返回以下内容:

js
return {
  paths: [
    { params: { id: '1' }},
    {
      params: { id: '2' },
      // 配置了 i18n 后,也可以返回该路径的 locale
      locale: "en",
    },
  ],
  fallback: ...
}

然后,Next.js 将在 next build 期间使用 pages/posts/[id].js 中的页面组件静态生成 /posts/1 和 /posts/2。

每个 params 对象的值必须与页面名称中使用的参数相匹配:

  • 如果页面名称是 pages/posts/[postId]/[commentId],那么 params 应包含 postId 和 commentId。
  • 如果页面名称使用通配路由,如 pages/[...slug],那么 params 应包含 slug(它是一个数组)。如果这个数组是 ['hello', 'world'],那么 Next.js 将静态生成 /hello/world 处的页面。
  • 如果页面使用可选通配路由,可使用 null、[]、undefined 或 false 来渲染最顶层的路由。例如,如果你为 pages/[[...slug]] 提供 slug: false,Next.js 将静态生成 / 页面。

params 字符串区分大小写,理想情况下应将其规范化以确保正确生成路径。例如,如果某个参数返回 WoRLD,则只有当实际访问的路径是 WoRLD 时才会匹配,而不是 world 或 World。

除 params 对象外,当配置了 i18n 时,还可以返回一个 locale 字段,用于为所生成的路径配置 locale。

fallback: false#

如果 fallback 为 false,那么任何未被 getStaticPaths 返回的路径都将导致 404 页面。

运行 next build 时,Next.js 会检查 getStaticPaths 是否返回了 fallback: false,然后仅构建 getStaticPaths 返回的路径。如果要创建的路径数量较少,或者不经常添加新页面数据,则此选项很有用。如果你发现需要添加更多路径,而此时使用的是 fallback: false,则需要再次运行 next build 以生成新路径。

以下示例使用名为 pages/posts/[id].js 的页面为每个博客文章预渲染一个页面。博客文章列表将从 CMS 获取并由 getStaticPaths 返回。然后,对于每个页面,它会使用 getStaticProps 从 CMS 获取文章数据。

pages/posts/[id].js
function Post({ post }) {
  // 渲染文章...
}

// 此函数在构建时被调用
export async function getStaticPaths() {
  // 调用外部 API 端点以获取文章
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // 根据文章获取我们想要预渲染的路径
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // 我们将在构建时仅预渲染这些路径。
  // { fallback: false } 表示其他路由应返回 404。
  return { paths, fallback: false }
}

// 此函数同样在构建时被调用
export async function getStaticProps({ params }) {
  // params 包含文章的 `id`。
  // 如果路由类似于 /posts/1,那么 params.id 为 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // 通过 props 将文章数据传递给页面
  return { props: { post } }
}

export default Post

fallback: true#

<details> <summary>示例</summary>

</details>

如果 fallback 为 true,那么 getStaticProps 的行为会发生以下变化:

  • getStaticPaths 返回的路径将在构建时由 getStaticProps 渲染为 HTML。
  • 未在构建时生成的路径不会导致 404 页面。相反,当首次请求此类路径时,Next.js 将提供一个“fallback”版本的页面。诸如 Google 之类的网络爬虫不会看到 fallback,而是该路径的行为将如同 fallback: 'blocking'。
  • 当通过 next/link 或 next/router(客户端)导航到一个带有 fallback: true 的页面时,Next.js 不会 提供 fallback,而是该页面的行为将如同 fallback: 'blocking'。
  • 在后台,Next.js 将静态生成所请求路径的 HTML 和 JSON。这包括运行 getStaticProps。
  • 完成后,浏览器会收到所生成路径的 JSON。它将用于使用所需的 props 自动渲染页面。从用户的角度来看,页面将从 fallback 页面切换为完整页面。
  • 同时,Next.js 会将此路径添加到预渲染页面列表中。后续对同一路径的请求将提供已生成的页面,就像其他在构建时预渲染的页面一样。

小知识:使用 output: 'export' 时不支持 fallback: true。

fallback: true 何时有用?#

如果你的应用拥有大量依赖数据的静态页面(例如一个大型电子商务网站),那么 fallback: true 非常有用。如果你想预渲染所有产品页面,构建将花费很长时间。

相反,你可以只静态生成一小部分页面,其余页面使用 fallback: true。当有人请求尚未生成的页面时,用户将看到带有加载指示器或骨架组件的页面。

不久之后,getStaticProps 完成,页面将使用请求的数据进行渲染。从那时起,每个请求同一页面的人都将获得静态预渲染的页面。

这确保用户始终获得快速体验,同时保留快速构建和静态生成的优势。

fallback: true 不会更新已生成的页面,为此请查看增量静态再生成。

fallback: 'blocking'#

如果 fallback 为 'blocking',未被 getStaticPaths 返回的新路径将等待 HTML 生成,这与 SSR 相同(这就是 blocking 的由来),然后会被缓存以供后续请求使用,因此每个路径只会发生一次。

getStaticProps 的行为如下:

  • getStaticPaths 返回的路径将在构建时由 getStaticProps 渲染为 HTML。
  • 未在构建时生成的路径不会导致 404 页面。相反,Next.js 将在首次请求时进行 SSR 并返回生成的 HTML。
  • 完成后,浏览器会收到所生成路径的 HTML。从用户的角度来看,它将从“浏览器正在请求页面”转变为“完整页面已加载”。不会出现加载/fallback 状态的闪烁。
  • 同时,Next.js 会将此路径添加到预渲染页面列表中。后续对同一路径的请求将提供已生成的页面,就像其他在构建时预渲染的页面一样。

默认情况下,fallback: 'blocking' 不会更新已生成的页面。要更新已生成的页面,请将增量静态再生成与 fallback: 'blocking' 结合使用。

小知识:使用 output: 'export' 时不支持 fallback: 'blocking'。

Fallback 页面#

在页面的“fallback”版本中:

  • 页面的 props 将为空。
  • 使用 router,你可以检测是否正在渲染 fallback,此时 router.isFallback 将为 true。

以下示例展示了 isFallback 的用法:

pages/posts/[id].js
import { useRouter } from 'next/router'

function Post({ post }) {
  const router = useRouter()

  // 如果页面尚未生成,将显示此内容
  // 在 getStaticProps() 运行完成之前最初显示
  if (router.isFallback) {
    return <div>Loading...</div>
  }

  // 渲染文章...
}

// 此函数在构建时被调用
export async function getStaticPaths() {
  return {
    // 构建时仅生成 `/posts/1` 和 `/posts/2`
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    // 启用额外页面的静态生成
    // 例如:`/posts/3`
    fallback: true,
  }
}

// 此函数同样在构建时被调用
export async function getStaticProps({ params }) {
  // params 包含文章的 `id`。
  // 如果路由类似于 /posts/1,那么 params.id 为 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // 通过 props 将文章数据传递给页面
  return {
    props: { post },
    // 每秒最多重新生成一次文章
    // 如果有请求进来
    revalidate: 1,
  }
}

export default Post

版本历史#

版本变更
v13.4.0App Router 现已稳定,简化了数据获取,包括 generateStaticParams()
v12.2.0按需增量静态再生成已稳定。
v12.1.0新增按需增量静态再生成(beta)。
v9.5.0稳定的增量静态再生成
v9.3.0引入 getStaticPaths。
Next.js 中文网