getStaticPaths

如果你的頁面需要做動態路由時使用 getStaticProps ，同時你需要去列舉需要做靜態生成的路徑。

當你的函數在你的頁面導出 getStaticPaths（靜態生成）同時使用動態路由，Next.js將會靜態的提前渲染所有從getStaticPaths導出的所有路徑。

// pages/posts/[id].js

// 生成 `/posts/1` 和 `/posts/2`
export async function getStaticPaths() {
  return {
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    fallback: false, // can also be true or 'blocking'
  }
}

// 使用`getStaticPaths`時需要搭配`getStaticProps`
export async function getStaticProps(context) {
  return {
    // 這裡的回傳值會導入到頁面的props中
    props: { post: {} },
  }
}

export default function Post({ post }) {
  // 渲染 post...
}

getStaticPaths API 文件 涵蓋了可以與 getStaticPaths 一起使用的所有參數和props。

何時可以使用 getStaticPaths ？

如果你是夠過動態路由去渲染靜態頁面你應該使用 getStaticPaths 而且：

• 資料來自headless CMS
• 資料來自資料庫
• 資料來自文件系統
• 資料是可以公開快取 (不是用戶特定)
• 頁面必須做提前渲染 (給 SEO) 而且運行速度非常快 — getStaticProps 生成 HTML 和 JSON 檔案, 兩者都可以由 CDN 快取以提高性能 。

getStaticPaths 什麼時候運行？

getStaticPaths 只會在生產環境中運行，不會在運行時調用。您可以驗證在 getStaticPaths 中編寫的代碼已從客戶端包中刪除 使用這個工具。

getStaticProps運行時是如何訪問getStaticPaths的？

• getStaticProps 在 next build 期間運行，用於構建期間返回的任何 paths 。
• getStaticProps 當使用 fallback: true 將會在背景執行。
• 使用 fallback：blocking 時，在初始渲染之前調用 getStaticProps 。

哪裡可以使用 getStaticPaths ？

• getStaticPaths 必須 和 getStaticProps 一起使用。
• 你 不能 把 getStaticPaths 和 getServerSideProps 一起使用。
• 您可以從同樣使用 getStaticProps 動態路由 導出getStaticPaths。
• 你 不能 在非page file導出getStaticPaths(例如 你的 components 檔案夾)。
• You must export getStaticPaths as a standalone function, and not a property of the page component 。

在開發中的每個請求上運行

在開發中（next dev），getStaticPaths 將在每個請求上被調用。

按造需求生成路徑

getStaticPaths 許您控制在構建期間生成哪些頁面，而不是按需生成 fallback。 在構建期間生成更多頁面將導致構建速度變慢。

您可以通過為 paths 返回一個空數組來延遲按需生成所有頁面。這在將 Next.js 應用程序部署到多個環境時特別有用。例如，您可以通過按需生成所有頁面以供預覽（但不是生產構建）來加快構建速度。這對於擁有成百上千個靜態頁面的網站很有幫助。

// pages/posts/[id].js

export async function getStaticPaths() {
  //  當以下是true時 (在預覽環境) 不會去
  //  預渲染任何靜態頁面
  // （構建速度較快，但初始頁面加載速度較慢）
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // 呼叫額外的API端點去獲取posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // 根據posts獲取我們想要預渲染的路徑
  // 在生產環境中，預渲染所有頁面
  //（構建速度較慢，但初始頁面加載速度較快）
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } 意思是如果其他路徑沒有匹配到將回傳404
  return { paths, fallback: false }
}

相關

有關下一步的更多訊息，我們推薦以下的內容：