路由區段設定

路由區段選項允許您透過直接匯出以下變數來設定頁面、佈局或路由處理器的行為。

選項

experimental_ppr

為佈局或頁面啟用部分預渲染 (PPR)。

export const experimental_ppr = true
// true | false

dynamic

將佈局或頁面的動態行為變更為完全靜態或完全動態。

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

注意事項：app 目錄中的新模型傾向於在 fetch 請求層級進行精細的快取控制，而不是 pages 目錄中頁面層級的 getServerSideProps 和 getStaticProps 的全有或全無二元模型。dynamic 選項是一種方便地選擇回到先前模型的方法，並提供更簡單的遷移路徑。

• 'auto'（預設）：預設選項，盡可能快取，但不阻止任何組件選擇動態行為。

• 'force-dynamic'：強制執行動態渲染，這將導致路由在每次使用者請求時皆進行渲染。此選項等同於在 pages 目錄中使用

  • getServerSideProps()。
  • 將佈局或頁面中每個 fetch() 請求的選項設定為 { cache: 'no-store', next: { revalidate: 0 } }。
  • 將區段設定設為 export const fetchCache = 'force-no-store'

• 'error'：強制執行靜態渲染並快取佈局或頁面的資料，如果任何組件使用動態 API 或未快取的資料，則會導致錯誤。此選項等同於在 pages 目錄中使用

  • getStaticProps()。
  • 將佈局或頁面中每個 fetch() 請求的選項設定為 { cache: 'force-cache' }。
  • 將區段設定設為 fetchCache = 'only-cache', dynamicParams = false。
  • dynamic = 'error' 會將 dynamicParams 的預設值從 true 變更為 false。您可以透過手動設定 dynamicParams = true，選擇重新以動態方式渲染 generateStaticParams 未產生的動態參數頁面。

• 'force-static'：強制執行靜態渲染並快取佈局或頁面的資料，方法是強制 cookies、headers() 和 useSearchParams() 返回空值。

注意事項:

• 關於如何從 getServerSideProps 和 getStaticProps 遷移到 dynamic: 'force-dynamic' 和 dynamic: 'error' 的說明，請參閱升級指南。

dynamicParams

控制當訪問未由 generateStaticParams 生成的動態區段時會發生什麼。

export const dynamicParams = true // true | false,

• true（預設值）：未包含在 generateStaticParams 中的動態區段將會按需生成。
• false：未包含在 generateStaticParams 中的動態區段將會返回 404 錯誤。

注意事項:

• 此選項取代了 pages 目錄中 getStaticPaths 的 fallback: true | false | blocking 選項。
• 要靜態渲染所有路徑在第一次被訪問時，您需要在 generateStaticParams 中返回一個空陣列，或使用 export const dynamic = 'force-static'。
• 當 dynamicParams = true 時，該區段會使用串流伺服器渲染。
• 如果使用了 dynamic = 'error' 和 dynamic = 'force-static'，它會將 dynamicParams 的預設值更改為 false。

revalidate

設定版面或頁面的預設重新驗證時間。此選項不會覆蓋個別 fetch 請求所設定的 revalidate 值。

export const revalidate = false
// false | 0 | number

• false（預設值）：預設的啟發式方法，會快取任何將 cache 選項設為 'force-cache' 的 fetch 請求，或是在使用動態 API 之前發現的請求。語義上等同於 revalidate: Infinity，這實際上意味著資源應無限期快取。個別的 fetch 請求仍然可以使用 cache: 'no-store' 或 revalidate: 0 來避免被快取，並使路由動態渲染。或者，將 revalidate 設定為比路由預設值低的正數，以增加路由的重新驗證頻率。
• 0：即使未發現動態 API 或未快取的資料提取，也要確保佈局或頁面始終動態渲染。此選項會將未設定 cache 選項的 fetch 請求的預設值更改為 'no-store'，但會保留選擇 'force-cache' 或使用正 revalidate 值的 fetch 請求。
• number：（以秒為單位）將佈局或頁面的預設重新驗證頻率設定為 n 秒。

注意事項:

• revalidate 值需要可靜態分析。例如，revalidate = 600 有效，但 revalidate = 60 * 10 無效。
• 使用 runtime = 'edge' 時，revalidate 值不可用。
• 在開發過程中，頁面*始終*按需渲染，且永不會被快取。這讓您可以立即看到變更，而無需等待重新驗證期結束。

重新驗證頻率

• 單一路由中每個佈局和頁面的最低 revalidate 值將決定*整個*路由的重新驗證頻率。這可確保子頁面与其父佈局的重新驗證頻率相同。
• 個別的 fetch 請求可以設定比路由預設 revalidate 值更低的 revalidate 值，以增加整個路由的重新驗證頻率。這讓您可以根據某些條件，動態選擇更頻繁地重新驗證特定路由。

fetchCache

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

runtime

我們建議使用 Node.js 執行環境來渲染您的應用程式，並使用 Edge 執行環境來處理中中間件（唯一支援的選項）。

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

• 'nodejs'（預設）
• 'edge'

深入瞭解不同的執行環境。

preferredRegion

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

對 preferredRegion 的支援以及支援的地區取決於您的部署平台。

注意事項:

• 如果未指定 preferredRegion，它將繼承最接近的父版面配置的選項。
• 根版面配置預設為 all 地區。

maxDuration

預設情況下，Next.js 不會限制伺服器端邏輯的執行時間（渲染頁面或處理 API）。部署平台可以使用 Next.js 建置輸出中的 maxDuration 來新增特定的執行時間限制。例如，在 Vercel 上。

注意：此設定需要 Next.js 13.4.10 或更高版本。

export const maxDuration = 5

注意事項:

• 如果使用伺服器動作，請在頁面層級設定 maxDuration 來更改頁面上所有伺服器動作的預設逾時時間。

generateStaticParams

generateStaticParams 函式可以與動態路由區段結合使用，以定義在建置時靜態產生而不是在請求時按需產生的路由區段參數列表。

有關更多詳細資訊，請參閱API 參考。

版本歷史記錄