路由區段設定 (Route Segment Config)

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

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

須知事項:

• 目前設定選項的值需要是靜態可分析的。例如 revalidate = 600 是有效的，但 revalidate = 60 * 10 則無效。

選項

dynamic

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

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

須知事項：app 目錄中的新模型傾向於在 fetch 請求層級進行細粒度的快取控制，而不是 pages 目錄中頁面層級的 getServerSideProps 和 getStaticProps 的全有或全無模型。dynamic 選項是一種回退到先前模型的便利方式，並提供了更簡單的遷移路徑。

• 'auto' (預設值)：預設選項，盡可能進行快取，同時不阻止任何元件選擇動態行為。
• 'force-dynamic'：透過禁用所有 fetch 請求的快取並始終重新驗證，強制動態渲染和未快取的資料獲取。此選項等效於：
  • pages 目錄中的 getServerSideProps()。
  • 將佈局或頁面中每個 fetch() 請求的選項設定為 { cache: 'no-store', next: { revalidate: 0 } }。
  • 將區段配置設定為 export const fetchCache = 'force-no-store'。
• 'error'：如果任何元件使用 動態函數 (dynamic functions) 或未快取的資料，則會導致錯誤，從而強制靜態渲染並快取佈局或頁面的資料。此選項等效於：
  • 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 選項。
• 當 dynamicParams = true 時，該區段使用 串流伺服器渲染 (Streaming Server Rendering)。
• 如果使用了 dynamic = 'error' 和 dynamic = 'force-static'，則會將 dynamicParams 的預設值變更為 false。

revalidate

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

export const revalidate = false
// false | 'force-cache' | 0 | number

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

須知事項：revalidate 選項僅在使用 Node.js 執行環境 (Node.js Runtime) 時可用。這意味著將 revalidate 選項與 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

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

• nodejs (預設值)
• edge

了解更多關於 Edge 和 Node.js 執行環境 (Edge and Node.js runtimes)。

preferredRegion

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

對 preferredRegion 和支援的區域的支援取決於您的部署平台。

須知事項：

• 如果未指定 preferredRegion，它將繼承最接近的父佈局的選項。
• 根佈局預設為 all 區域。

maxDuration

根據您的部署平台，您可能可以使用更高的函數預設執行時間。此設定允許您在計劃限制內選擇更高的執行時間。 注意：此設定需要 Next.js 13.4.10 或更高版本。

export const maxDuration = 5

須知事項：

• 如果未指定 maxDuration，預設值取決於您的部署平台和計劃。

generateStaticParams

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

詳情請參閱 API 參考。