Nuxt 4 パターン

SSR、ハイブリッドレンダリング、ルートルール、またはページレベルのデータ取得を持つ Nuxt 4 アプリケーションを構築またはデバッグするときに使用します。

いつ有効化するか

• サーバー HTML とクライアント状態の間で水合の不一致が発生している
• ルートレベルのレンダリング決定（プリレンダリング、SWR、ISR、またはクライアントのみのセクションなど）
• 遅延ロード、遅延水合、またはペイロードサイズに関するパフォーマンス作業
• useFetch、useAsyncData、または $fetch を使用したページまたはコンポーネントのデータ取得
• ルートパラメータ、ミドルウェア、または SSR/クライアント差異に関連する Nuxt ルーティングの問題

水合安全性

• 初回レンダリングが確定的であることを維持します。Date.now()、Math.random()、ブラウザのみの API、またはストレージ読み取りを SSR レンダリングされたテンプレート状態に直接配置しないでください。
• サーバーが同じマークアップを生成できない場合は、ブラウザのみのロジックを onMounted()、import.meta.client、ClientOnly、または .client.vue コンポーネントの背後に移動します。
• vue-router からのものではなく、Nuxt の useRoute() コンポーザブルを使用します。
• SSR レンダリングされたマークアップを駆動するために route.fullPath を使用しないでください。URL フラグメントはクライアントのみであり、水合の不一致を引き起こす可能性があります。
• ssr: false を不一致を解決するためのデフォルト修正ではなく、真のブラウザのみの領域の脱出ハッチとして扱います。

データ取得

• ページとコンポーネントでは、SSR 安全な API 読み取りのために await useFetch() を優先します。サーバー取得したデータを Nuxt ペイロードに転送し、水合中の 2 回目の取得を回避します。
• データ取得がシンプルな $fetch() 呼び出しでない場合、またはカスタムキーが必要な場合、または複数の非同期ソースを組み合わせている場合は useAsyncData() を使用します。
• キャッシュを再利用し、予測可能なリフレッシュ動作を実現するために、useAsyncData() に安定したキーを提供します。
• useAsyncData() ハンドラーを副作用がないように保ちます。SSR と水合中に実行される可能性があります。
• ユーザートリガーの書き込みまたはクライアントのみの操作には $fetch() を使用し、SSR 水合から取得すべきトップレベルのページデータには使用しないでください。
• ナビゲーションをブロックするべきではない非重要データの場合、lazy: true、useLazyFetch()、または useLazyAsyncData() を使用します。UI で status === 'pending' を処理します。
• SEO または初回描画に不要なデータについてのみ server: false を使用します。
• pick を使用してペイロードサイズをトリムし、深いリアクティビティが不要な場合は浅いペイロードを優先します。

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 が実際に必要な場合にのみコードブロックが読み込まれるようにします。
• スクロール下のコンテンツまたは非重要のインタラクティブ UI に対して遅延水合を使用します。

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

• カスタム戦略については、可視性またはアイドル戦略と組み合わせて defineLazyHydrationComponent() を使用します。
• Nuxt 遅延水合は単一ファイルコンポーネントに適用されます。遅延水合されたコンポーネントに新しい props を渡すと、水合が即座にトリガーされます。
• 内部ナビゲーションに NuxtLink を使用して、Nuxt がルートコンポーネントと生成されたペイロードをプリフェッチできるようにします。

チェックリスト

• 初回 SSR レンダリングと水合後のクライアントレンダリングは同じマークアップを生成する
• ページデータは トップレベルの $fetch ではなく useFetch または useAsyncData を使用している
• 非重要データは遅延ロードされ、明示的な読み込み UI がある
• ルートルールはページの SEO と鮮度要件を満たしている
• 重いインタラクティブコンポーネントは遅延ロードまたは遅延水合されている