路由區段設定

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

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

選項

experimental_ppr

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

export const experimental_ppr = true
// true | false

export const experimental_ppr = true
// true | false

dynamic

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

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

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,

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

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'

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'

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

• 'nodejs' (預設)
• 'edge'

preferredRegion

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

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

export const maxDuration = 5

須知：

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

generateStaticParams

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

詳情請參閱 API 參考。

版本歷史