跳到主要內容
API 參考函式cacheLife

cacheLife

此功能目前在 Canary 頻道中提供，並且可能會有所變動。請升級 Next.js 來試用，並在 GitHub 上分享您的意見回饋。

cacheLife 函式用於設定函式或元件的快取生命週期。它應與 use cache 指令一起使用，並在函式或元件的範圍內使用。

用法

若要使用 cacheLife，請在您的 next.config.js 檔案中啟用 dynamicIO 標記

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}
 
export default nextConfig

然後，在函式或元件的範圍內匯入並調用 cacheLife 函式

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

參考

預設快取設定檔

Next.js 提供一組具名的快取設定檔，這些設定檔是根據各種時間尺度建模的。如果您在 cacheLife 函式中未指定快取設定檔，並且與 use cache 指令一起使用，Next.js 將自動套用「default」快取設定檔。

但是，我們建議在使用 use cache 指令時，始終新增快取設定檔，以明確定義快取行為。

設定檔過時重新驗證到期描述
default未定義15 分鐘INFINITE_CACHE預設設定檔，適用於不需要頻繁更新的內容
seconds未定義1 秒1 分鐘適用於需要近乎即時更新的快速變更內容
minutes5 分鐘1 分鐘1 小時適用於在一個小時內頻繁更新的內容
hours5 分鐘1 小時1 天適用於每天更新但可能稍微過時的內容
days5 分鐘1 天1 週適用於每週更新但可能過時一天的內容
weeks5 分鐘1 週1 個月適用於每月更新但可能過時一週的內容
max5 分鐘1 個月INFINITE_CACHE適用於非常穩定的內容，幾乎不需要更新

用於參考快取設定檔的字串值沒有固有的含義；相反地，它們充當語義標籤。這可讓您更瞭解和管理程式碼庫中的快取內容。

自訂快取設定檔

您可以透過將自訂快取設定檔新增至 next.config.ts 檔案中的 cacheLife 選項來設定它們。

快取設定檔是包含下列屬性的物件

屬性值描述需求
stale數字用戶端應快取值而不檢查伺服器的持續時間。選用
revalidate數字快取應在伺服器上重新整理的頻率；重新驗證時可能會提供過時的值。選用
expire數字值在切換到動態抓取之前可以保持過時的最長持續時間；必須長於 revalidate。選用 - 必須長於 revalidate

「stale」屬性與 staleTimes 設定不同之處在於，它專門控制用戶端路由器快取。雖然 staleTimes 是一個影響動態和靜態資料所有執行個體的全域設定，但 cacheLife 設定可讓您在每個函式或每個路由的基礎上定義「stale」時間。

需知：「stale」屬性不會設定 Cache-control: max-age 標頭。它而是控制用戶端路由器快取。

範例

定義可重複使用的快取設定檔

您可以透過在 next.config.ts 檔案中定義快取設定檔來建立可重複使用的快取設定檔。選擇適合您用例的名稱，並為 stale、revalidate 和 expire 屬性設定值。您可以根據需要建立任意數量的自訂快取設定檔。每個設定檔都可以透過其名稱（作為傳遞至 cacheLife 函式的字串值）來參考。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 days
        revalidate: 60 * 60 * 24, // 1 day
        expire: 60 * 60 * 24 * 14, // 14 days
      },
    },
  },
}
 
module.exports = nextConfig

上面的範例快取 14 天、每天檢查更新，並在 14 天後使快取過期。然後，您可以透過其名稱在整個應用程式中參考此設定檔

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

覆寫預設快取設定檔

雖然預設快取設定檔提供了一種有用的方式來思考任何給定部分的可快取輸出可能是多麼新鮮或過時，但您可能更喜歡不同的具名設定檔，以便更好地與您的應用程式快取策略保持一致。

您可以透過建立與預設值同名的新設定來覆寫預設的具名快取設定檔。

下面的範例示範如何覆寫預設的「days」快取設定檔

next.config.ts
const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 hour
        revalidate: 900, // 15 minutes
        expire: 86400, // 1 day
      },
    },
  },
}
 
module.exports = nextConfig

內聯定義快取設定檔

對於特定用例，您可以透過將物件傳遞至 cacheLife 函式來設定自訂快取設定檔

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife({
    stale: 3600, // 1 hour
    revalidate: 900, // 15 minutes
    expire: 86400, // 1 day
  })
 
  return <div>Page</div>
}

此內聯快取設定檔將僅套用於建立它的函式或檔案中。如果您想在整個應用程式中重複使用相同的設定檔，您可以將設定新增至 next.config.ts 檔案的 cacheLife 屬性。

use cache 和 cacheLife 的巢狀用法

在同一個路由或元件樹狀結構中定義多個快取行為時，如果內部快取指定了自己的 cacheLife 設定檔，則外部快取將遵循其中最短的快取持續時間。這僅在外部快取沒有定義自己的明確 cacheLife 設定檔時適用。

例如，如果您將 use cache 指令新增至您的頁面，而未指定快取設定檔，則將隱式套用預設快取設定檔 (cacheLife(”default”))。如果匯入到頁面的元件也使用具有其自身快取設定檔的 use cache 指令，則會比較外部和內部快取設定檔，並套用設定檔中設定的最短持續時間。

app/components/parent.tsx
// Parent component
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'
 
export async function ParentComponent() {
  'use cache'
  cacheLife('days')
 
  return (
    <div>
      <ChildComponent />
    </div>
  )
}

在另一個檔案中，我們定義了匯入的 Child 元件

app/components/child.tsx
// Child component
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>
 
  // This component's cache will respect the shorter 'hours' profile
}

相關內容

檢視相關的 API 參考。

dynamicIO

瞭解如何在 Next.js 中啟用 dynamicIO 標記。

use cache

瞭解如何使用 use cache 指令在您的 Next.js 應用程式中快取資料。

revalidateTag

revalidateTag 函式的 API 參考。

cacheTag

瞭解如何使用 cacheTag 函式來管理您的 Next.js 應用程式中的快取失效。