getStaticProps

如果您從頁面導出名為 getStaticProps 的函數（靜態網站生成），Next.js 將在構建時使用 getStaticProps 返回的屬性預渲染此頁面。

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
}

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
}

請注意，無論渲染類型為何，任何 props 都會傳遞給頁面元件，並可在初始 HTML 中於客戶端查看。這是為了讓頁面能正確進行水合 (hydrate)。請確保不要在 props 中傳遞任何不應在客戶端顯示的敏感資訊。

getStaticProps API 參考文件涵蓋了所有可與 getStaticProps 一起使用的參數和屬性。

何時應該使用 getStaticProps？

在以下情況下應使用 getStaticProps：

渲染頁面所需的資料在使用者請求前已於構建時準備就緒
資料來自無頭 CMS (headless CMS)
頁面必須預渲染（為了 SEO）且速度極快 — getStaticProps 會生成 HTML 和 JSON 文件，兩者均可透過 CDN 快取以提高效能
資料可公開快取（非使用者特定）。在某些特定情況下，可透過使用中介軟體 (Middleware) 重寫路徑來繞過此條件

getStaticProps 何時執行

getStaticProps 始終在伺服器端執行，絕不在客戶端執行。您可以使用此工具驗證 getStaticProps 中的程式碼已從客戶端套件中移除。

getStaticProps 在執行 next build 時始終會執行
使用 fallback: true 時，getStaticProps 會在背景執行
使用 fallback: blocking 時，getStaticProps 會在初始渲染前呼叫
使用 revalidate 時，getStaticProps 會在背景執行
使用 revalidate() 時，getStaticProps 會按需在背景執行

與增量靜態再生 (Incremental Static Regeneration) 結合使用時，getStaticProps 會在重新驗證過期頁面的同時於背景執行，並將新頁面提供給瀏覽器。

getStaticProps 無法存取傳入的請求（如查詢參數或 HTTP 標頭），因為它生成的是靜態 HTML。如果您需要存取頁面的請求，請考慮在使用 getStaticProps 的同時使用中介軟體 (Middleware)。

使用 getStaticProps 從 CMS 獲取資料

以下範例展示如何從 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` 作為屬性
  return {
    props: {
      posts,
    },
  }
}

// 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` 作為屬性
  return {
    props: {
      posts,
    },
  }
}

getStaticProps API 參考文件涵蓋了所有可與 getStaticProps 一起使用的參數和屬性。

直接編寫伺服器端程式碼

由於 getStaticProps 僅在伺服器端執行，因此它永遠不會在客戶端執行。它甚至不會包含在瀏覽器的 JS 套件中，因此您可以編寫直接資料庫查詢而不會將其發送到瀏覽器。

這意味著您可以直接在 getStaticProps 中編寫伺服器端程式碼，而不是從 getStaticProps 中獲取API 路由（該路由本身從外部來源獲取資料）。

以下是一個範例。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` 路由
  const posts = await loadPosts()

  // 返回的屬性將傳遞給頁面元件
  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 文件（在構建時預先計算）並將其用作頁面元件的屬性。這意味著客戶端頁面轉換不會呼叫 getStaticProps，因為僅使用導出的 JSON。

使用增量靜態生成時，getStaticProps 將在背景執行以生成客戶端導航所需的 JSON。您可能會看到對同一頁面發出的多個請求，但這是預期的行為，不會影響最終使用者的效能。

可以在何處使用 getStaticProps

getStaticProps 只能從頁面導出。您不能從非頁面文件、_app、_document 或 _error 導出它。

此限制的原因之一是 React 需要在頁面渲染前擁有所有必需的資料。

此外，您必須將 getStaticProps 作為獨立函數導出 — 如果將 getStaticProps 作為頁面元件的屬性添加，它將無法工作。

須知：如果您建立了自訂應用程式，請確保按照連結文件中的說明將 pageProps 傳遞給頁面元件，否則屬性將為空。

在開發環境中每次請求都會執行

在開發環境中 (next dev)，getStaticProps 會在每次請求時呼叫。

預覽模式

您可以使用預覽模式 (Preview Mode) 暫時繞過靜態生成，並在請求時而非構建時渲染頁面。例如，您可能正在使用無頭 CMS 並希望在草稿發布前預覽它們。

On this page