getStaticProps

匯出名為 getStaticProps 的函式將會在建置時使用從函式回傳的屬性預先渲染頁面。

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
}

您可以在頂層作用域導入模組，以在 getStaticProps 中使用。使用的導入將**不會被捆綁到客戶端**。這表示您可以**直接在 getStaticProps 中撰寫伺服器端程式碼**，包括從資料庫擷取資料。

上下文參數

context 參數是一個物件，包含以下鍵值：

名稱	說明
`params`	包含使用動態路由的頁面的路由參數。例如，如果頁面名稱是 `[id].js`，則 `params` 看起來會像 `{ id: ... }`。您應該將此與 `getStaticPaths` 一起使用，我們稍後會解釋。
`preview`	（已棄用，改用 `draftMode`）如果頁面處於預覽模式，則 `preview` 為 `true`，否則為 `false`。
`previewData`	（已棄用，改用 `draftMode`）由 `setPreviewData` 設定的預覽資料。
`draftMode`	如果頁面處於草稿模式，則 `draftMode` 為 `true`，否則為 `false`。
`locale`	包含啟用的地區設定（如果已啟用）。
`locales`	包含所有支援的地區設定（如果已啟用）。
`defaultLocale`	包含設定的預設地區設定（如果已啟用）。
`revalidateReason`	提供呼叫此函式的原因。可以是以下其中之一：「build」（在建置時執行）、「stale」（重新驗證期限已過期，或在開發模式中執行）、「on-demand」（透過隨需重新驗證觸發）。

getStaticProps 回傳值

getStaticProps 函式應該回傳一個物件，其中包含 props、redirect 或 notFound，後接一個**選用**的 revalidate 屬性。

`props`

props 物件是一個鍵值對，其中每個值都由頁面元件接收。它應該是一個可序列化物件，以便任何傳遞的屬性都可以使用JSON.stringify序列化。

export async function getStaticProps(context) {
  return {
    props: { message: `Next.js is awesome` }, // will be passed to the page component as props
  }
}

`revalidate`

revalidate 屬性是用於設定頁面重新產生的秒數（預設為 false 或不重新驗證）。

// This function gets called at build time on server-side.
// It may be called again, on a serverless function, if
// revalidation is enabled and a new request comes in
export async function getStaticProps() {
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  return {
    props: {
      posts,
    },
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every 10 seconds
    revalidate: 10, // In seconds
  }
}

深入了解增量靜態再生 (ISR)。

可以透過讀取 x-nextjs-cache 回應標頭的值來判斷使用 ISR 的頁面的快取狀態。可能的值如下：

MISS - 路徑不在快取中（最多只會發生一次，在第一次訪問時）
STALE - 路徑在快取中，但已超過重新驗證時間，因此將在背景更新
HIT - 路徑在快取中，且尚未超過重新驗證時間

`notFound`

notFound 布林值允許頁面返回 404 狀態和 404 頁面。設定 notFound: true 時，即使之前已成功產生頁面，該頁面仍會返回 404。這旨在支援使用者產生的內容被其作者移除等使用案例。請注意，notFound 會遵循此處描述的相同 revalidate 行為。

export async function getStaticProps(context) {
  const res = await fetch(`https://.../data`)
  const data = await res.json()
 
  if (!data) {
    return {
      notFound: true,
    }
  }
 
  return {
    props: { data }, // will be passed to the page component as props
  }
}

注意事項：對於 fallback: false 模式不需要 notFound，因為只有從 getStaticPaths 返回的路徑才會被預先渲染。

redirect

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 }, // will be passed to the page component as props
  }
}

如果在建置時就知道重新導向，則應將其新增至 next.config.js。

讀取檔案：使用 process.cwd()

import { promises as fs } from 'fs'
import path from 'path'
 
// posts will be populated at build time by getStaticProps()
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>
          <h3>{post.filename}</h3>
          <p>{post.content}</p>
        </li>
      ))}
    </ul>
  )
}
 
// This function gets called at build time on server-side.
// It won't be called on client-side, so you can even do
// direct database queries.
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')
 
    // Generally you would parse/transform the contents
    // For example you can transform markdown to HTML here
 
    return {
      filename,
      content: fileContents,
    }
  })
  // By returning { props: { posts } }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts: await Promise.all(posts),
    },
  }
}
 
export default Blog

版本歷史紀錄

版本	變更
`v13.4.0`	App Router 現已穩定，並簡化了資料擷取
`v12.2.0`	隨需增量靜態再生已穩定。
`v12.1.0`	隨需增量靜態再生已新增（測試版）。
`v10.0.0`	新增了 `locale`、`locales`、`defaultLocale` 和 `notFound` 選項。
`v10.0.0`	新增了 `fallback: 'blocking'` 返回選項。
`v9.5.0`	穩定的增量靜態再生
`v9.3.0`	引進了 `getStaticProps`。

這有幫助嗎？