nuxt4-patterns

Nuxt 4 模式

在建立或除錯具有 SSR、混合渲染、路由規則或頁面層級資料擷取的 Nuxt 4 應用程式時使用。

何時啟用

• 伺服器 HTML 與客戶端狀態之間的水合不一致
• 路由層級的渲染決策，例如預渲染、SWR、ISR 或僅客戶端區塊
• 關於延遲載入、延遲水合或 payload 大小的效能最佳化
• 使用 useFetch、useAsyncData 或 $fetch 進行頁面或元件資料擷取
• 與路由參數、中介軟體或 SSR/客戶端差異相關的 Nuxt 路由問題

水合安全

• 保持首次渲染確定性。不要將 Date.now()、Math.random()、僅瀏覽器 API 或儲存讀取直接放入 SSR 渲染的模板狀態中。
• 當伺服器無法產生相同標記時，將僅瀏覽器邏輯移至 onMounted()、import.meta.client、ClientOnly 或 .client.vue 元件之後。
• 使用 Nuxt 的 useRoute() composable，而不是來自 vue-router 的。
• 不要使用 route.fullPath 來驅動 SSR 渲染的標記。URL 片段僅限客戶端，這可能導致水合不一致。
• 將 ssr: false 視為真正僅瀏覽器區域的逃生艙口，而不是不一致的預設修復方式。

資料擷取

• 在頁面和元件中，優先使用 await useFetch() 進行 SSR 安全的 API 讀取。它會將伺服器擷取的資料轉發到 Nuxt payload 中，並避免在水合時進行第二次擷取。
• 當擷取器不是簡單的 $fetch() 呼叫、需要自訂鍵或組合多個非同步來源時，使用 useAsyncData()。
• 為 useAsyncData() 提供穩定的鍵，以利快取重複使用和可預測的重新整理行為。
• 保持 useAsyncData() 處理程序無副作用。它們可以在 SSR 和水合期間執行。
• 對使用者觸發的寫入或僅客戶端操作使用 $fetch()，而不是應該從 SSR 水合的頂層頁面資料。
• 對不應阻塞導航的非關鍵資料使用 lazy: true、useLazyFetch() 或 useLazyAsyncData()。在 UI 中處理 status === 'pending'。
• 僅對 SEO 或首次繪製不需要的資料使用 server: false。
• 使用 pick 縮減 payload 大小，並在不需要深層響應性時偏好較淺的 payload。

const route = useRoute()

const { data: article, status, error, refresh } = await useAsyncData(
  () => `article:${route.params.slug}`,
  () => $fetch(`/api/articles/${route.params.slug}`),
)

const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
  lazy: true,
  server: false,
})

路由規則

在 nuxt.config.ts 中優先使用 routeRules 來設定渲染和快取策略：

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/products/**': { swr: 3600 },
    '/blog/**': { isr: true },
    '/admin/**': { ssr: false },
    '/api/**': { cache: { maxAge: 60 * 60 } },
  },
})

• prerender：建置時產生靜態 HTML
• swr：提供快取內容並在背景重新驗證
• isr：在支援的平台上進行增量靜態再生
• ssr: false：客戶端渲染的路由
• cache 或 redirect：Nitro 層級的響應行為

按路由群組選擇路由規則，而非全域套用。行銷頁面、目錄、儀表板和 API 通常需要不同的策略。

延遲載入與效能

• Nuxt 已按路由進行程式碼分割。在微調元件分割之前，保持路由邊界有意義。
• 使用 Lazy 前綴動態匯入非關鍵元件。
• 使用 v-if 條件渲染延遲元件，以便在 UI 實際需要之前不載入 chunk。
• 對摺疊以下或非關鍵的互動式 UI 使用延遲水合。

<template>
  <LazyRecommendations v-if="showRecommendations" />
  <LazyProductGallery hydrate-on-visible />
</template>

• 對於自訂策略，使用 defineLazyHydrationComponent() 搭配可見性或閒置策略。
• Nuxt 延遲水合適用於單一檔案元件。向延遲水合元件傳遞新 props 會立即觸發水合。
• 使用 NuxtLink 進行內部導航，以便 Nuxt 可以預取路由元件和產生的 payload。

審查清單

• 首次 SSR 渲染和水合後的客戶端渲染產生相同的標記
• 頁面資料使用 useFetch 或 useAsyncData，而非頂層的 $fetch
• 非關鍵資料是延遲的，並有明確的載入 UI
• 路由規則符合頁面的 SEO 和新鮮度要求
• 大型互動區塊已延遲載入或延遲水合