路由區段設定

如果啟用了 dynamicIO 標誌，本頁描述的選項將被禁用，並將在未來版本中被棄用。

路由區段選項允許您通過直接導出以下變數來配置 頁面、佈局 或 路由處理器 的行為：

選項

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'：強制 動態渲染，這將導致路由在每次用戶請求時渲染。此選項等同於：
  • 將佈局或頁面中每個 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() 返回空值。可以在使用 force-static 渲染的頁面或佈局中進行 revalidate、revalidatePath 或 revalidateTag。

須知：

• 有關如何從 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 時，區段使用 串流伺服器渲染。

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 = 600 是有效的，但 revalidate = 60 * 10 無效。
• 使用 runtime = 'edge' 時，重新驗證值不可用。
• 在開發環境中，頁面始終按需渲染且永不快取。這使您可以立即看到更改，而無需等待重新驗證期結束。

重新驗證頻率

• 單個路由的所有佈局和頁面中最低的 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 來添加特定的執行限制。

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

export const maxDuration = 5

須知：

• 如果使用 伺服器操作，請在頁面層級設置 maxDuration 以更改頁面上使用的所有伺服器操作的預設超時時間。

generateStaticParams

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

詳情請參閱 API 參考。

版本歷史