getStaticPaths

當從使用動態路由 (Dynamic Routes)的頁面導出名為 getStaticPaths 的函數時，Next.js 將會靜態預渲染 (pre-render) 所有由 getStaticPaths 指定的路徑。

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
}

getStaticPaths 回傳值

getStaticPaths 函數應回傳一個包含以下 必要 屬性的物件：

paths

paths 鍵決定了哪些路徑會被預渲染。例如，假設您有一個使用動態路由 (Dynamic Routes) 的頁面，名為 pages/posts/[id].js。如果您從此頁面導出 getStaticPaths 並為 paths 回傳以下內容：

return {
  paths: [
    { params: { id: '1' }},
    {
      params: { id: '2' },
      // 如果配置了 i18n，也可以回傳路徑的語言環境
      locale: "en",
    },
  ],
  fallback: ...
}

那麼，Next.js 將在 next build 期間使用 pages/posts/[id].js 中的頁面組件靜態生成 /posts/1 和 /posts/2。

每個 params 物件的值必須與頁面名稱中使用的參數匹配：

• 如果頁面名稱是 pages/posts/[postId]/[commentId]，那麼 params 應包含 postId 和 commentId。
• 如果頁面名稱使用全捕捉路由 (catch-all routes)，例如 pages/[...slug]，那麼 params 應包含 slug（這是一個陣列）。如果此陣列是 ['hello', 'world']，那麼 Next.js 將靜態生成位於 /hello/world 的頁面。
• 如果頁面使用可選全捕捉路由 (optional catch-all route)，請使用 null、[]、undefined 或 false 來渲染根路由。例如，如果您為 pages/[[...slug]] 提供 slug: false，Next.js 將靜態生成頁面 /。

params 字串是 區分大小寫 的，理想情況下應進行標準化以確保路徑正確生成。例如，如果某個參數回傳 WoRLD，則僅在實際訪問的路徑是 WoRLD 時才會匹配，而不是 world 或 World。

除了 params 物件外，當配置了 i18n 時，還可以回傳一個 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 獲取文章資料。

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

如果 fallback 是 true，則 getStaticProps 的行為會發生以下變化：

• 由 getStaticPaths 回傳的路徑將在構建時由 getStaticProps 渲染為 HTML。
• 在構建時未生成的路徑 不會 導致 404 頁面。相反，Next.js 將在首次請求此類路徑時提供一個「後備」版本的頁面。Google 等網路爬蟲不會收到後備頁面，而是該路徑的行為將如同 fallback: 'blocking'。
• 當通過 next/link 或 next/router（客戶端）導航到具有 fallback: true 的頁面時，Next.js 將 不會 提供後備頁面，而是該頁面的行為將如同 fallback: 'blocking'。
• 在後台，Next.js 將靜態生成請求路徑的 HTML 和 JSON。這包括運行 getStaticProps。
• 完成後，瀏覽器將收到生成路徑的 JSON。這將用於自動渲染具有所需 props 的頁面。從用戶的角度來看，頁面將從後備頁面切換為完整頁面。
• 同時，Next.js 將此路徑添加到預渲染頁面列表中。對同一路徑的後續請求將提供生成的頁面，如同其他在構建時預渲染的頁面。

須知：當使用 output: 'export' 時，不支援 fallback: true。

何時使用 fallback: true？

如果您的應用程式有大量依賴資料的靜態頁面（例如一個非常大的電子商務網站），fallback: true 會非常有用。如果您想預渲染所有產品頁面，構建將花費很長時間。

相反，您可以靜態生成一小部分頁面，並對其餘頁面使用 fallback: true。當有人請求尚未生成的頁面時，用戶將看到帶有加載指示器或骨架組件的頁面。

不久之後，getStaticProps 完成，頁面將使用請求的資料進行渲染。從現在開始，任何請求同一頁面的人都將獲得靜態預渲染的頁面。

這確保了用戶始終擁有快速的體驗，同時保留了快速構建和靜態生成的好處。

fallback: true 不會 更新 生成的頁面，如需更新，請參閱增量靜態再生 (Incremental Static Regeneration)。

fallback: 'blocking'

如果 fallback 是 'blocking'，則未由 getStaticPaths 回傳的新路徑將等待 HTML 生成，與 SSR 相同（因此稱為 blocking），然後緩存以供將來請求使用，因此每個路徑僅發生一次。

getStaticProps 的行為如下：

• 由 getStaticPaths 回傳的路徑將在構建時由 getStaticProps 渲染為 HTML。
• 在構建時未生成的路徑 不會 導致 404 頁面。相反，Next.js 將在首次請求時進行 SSR 並返回生成的 HTML。
• 完成後，瀏覽器將收到生成路徑的 HTML。從用戶的角度來看，它將從「瀏覽器正在請求頁面」過渡到「完整頁面已加載」。沒有加載/後備狀態的閃爍。
• 同時，Next.js 將此路徑添加到預渲染頁面列表中。對同一路徑的後續請求將提供生成的頁面，如同其他在構建時預渲染的頁面。

fallback: 'blocking' 預設情況下不會 更新 生成的頁面。要更新生成的頁面，請將增量靜態再生 (Incremental Static Regeneration) 與 fallback: 'blocking' 一起使用。

須知：當使用 output: 'export' 時，不支援 fallback: 'blocking'。

後備頁面

在頁面的「後備」版本中：

• 頁面的 props 將為空。
• 使用 router，您可以檢測是否正在渲染後備頁面，router.isFallback 將為 true。

以下範例展示了如何使用 isFallback：

import { useRouter } from 'next/router'

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

  // 如果頁面尚未生成，這將在初始時顯示
  // 直到 getStaticProps() 完成運行
  if (router.isFallback) {
    return <div>載入中...</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

版本歷史