Nuxt 4 Patterns & Optimization

Оптимизируйте приложения Nuxt 4 с Claude Code. Освойте SSR-безопасную загрузку данных, безопасность гидратации, правила маршрутизации SWR и оптимизацию производительности для Vue.js.

Дизайн ★ 172,009 GitHub (172,009 ★)

Nuxt 4 Patterns — это комплексный навык, предназначенный для помощи разработчикам в создании надежных и высокопроизводительных приложений на Nuxt 4 путем внедрения лучших практик серверного рендеринга (SSR). Он предоставляет экспертные рекомендации по предотвращению несоответствий гидратации, оптимизации получения данных с помощью useFetch и useAsyncData, а также настройке расширенных правил маршрутизации, таких как SWR и ISR. Независимо от того, отлаживаете ли вы сложные проблемы с гидратацией или проектируете крупномасштабное корпоративное приложение, этот навык гарантирует, что ваши проекты Nuxt будут эффективными, SEO-дружественными и поддерживаемыми.

Ключевые особенности

01Интеграция с Nitro: управление серверным кэшированием, редиректами и правилами маршрутизации для API.

02Безопасность SSR-гидратации: предотвращение несоответствий между серверным HTML и состоянием на клиенте.

03Расширенные правила маршрутизации: настройка стратегий рендеринга на уровне Nitro, включая SWR, ISR и предварительный рендеринг.

04Оптимизация получения данных: реализация безопасных для SSR паттернов с использованием useFetch и useAsyncData с сокращением полезной нагрузки.

05172 009 звезд на GitHub

06Ленивая загрузка и производительность: реализация разделения кода компонентов и стратегий отложенной гидратации.

Варианты использования

01Реализация эффективных стратегий получения данных, позволяющих избежать двойной выборки во время гидратации на клиенте.

02Настройка детальных правил производительности для маркетинговых страниц, каталогов товаров и административных панелей.

03Отладка ошибок «Несоответствие гидратации», вызванных недетерминированным рендерингом или использованием API, доступных только в браузере.

name	nuxt4-patterns
description	Nuxt 4 应用模式，涵盖水合安全、性能优化、路由规则、懒加载，以及使用 useFetch 和 useAsyncData 进行 SSR 安全的数据获取。
origin	ECC

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 组件后面。
使用 Nuxt 的 useRoute() 组合式函数，而不是来自 vue-router 的那个。
不要使用 route.fullPath 来驱动 SSR 渲染的标记。URL 片段是仅客户端的，这可能导致水合不匹配。
将 ssr: false 视为真正仅限浏览器区域的逃生舱口，而不是解决不匹配的默认修复方法。

数据获取

在页面和组件中，优先使用 await useFetch() 进行 SSR 安全的 API 读取。它将服务器获取的数据转发到 Nuxt 有效负载中，并避免在水合时进行第二次获取。
当数据获取器不是简单的 $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 渲染和水合后的客户端渲染产生相同的标记
页面数据使用 useFetch 或 useAsyncData，而非顶层的 $fetch
非关键数据是懒加载的，并具有明确的加载 UI
路由规则符合页面的 SEO 和新鲜度要求
重量级交互式组件是懒加载或延迟水合的

🧩 Что это

Этот skill — набор проверенных паттернов и оптимизаций для Nuxt 4 (и Nuxt 3 с оглядкой на 4). Он помогает разработчикам избегать типичных ошибок при SSR, управлять гидратацией, эффективно загружать данные, настраивать рендеринг на уровне маршрутов и оптимизировать производительность. Skill пригодится, когда вы сталкиваетесь с несоответствием HTML на сервере и клиенте, хотите внедрить ISR/SWR, ленивую загрузку или отложенную гидратацию компонентов.

⚙️ Как работает

🔒 Гидратационная безопасность (Hydration Safety)

Главное правило: сервер и клиент должны сгенерировать одинаковый HTML при первом рендере. Если этого не происходит — получаем ошибки гидратации.

Не используйте в шаблонах, рендерящихся на сервере, Date.now(), Math.random(), браузерные API (localStorage, window) или чтение из хранилищ. Они дадут разный результат на сервере и клиенте.
Выносите клиентский код в onMounted(), import.meta.client, оборачивайте в ClientOnly или используйте суффикс .client.vue.
Используйте useRoute() от Nuxt, а не от vue-router.
Не полагайтесь на route.fullPath в SSR-разметке — фрагмент URL (#hash) доступен только на клиенте.
ssr: false — крайняя мера для страниц, которые вообще не должны рендериться на сервере, а не способ «починить» гидратацию.

📡 Получение данных (Data Fetching)

useFetch() — основной инструмент для SSR-безопасного получения данных на страницах и в компонентах. Он автоматически передаёт результат с сервера в Nuxt payload, избегая повторного запроса на клиенте.
useAsyncData() — когда нужна кастомная логика (не просто $fetch), свой ключ кеша или объединение нескольких источников. Всегда передавайте стабильный ключ (первый аргумент).
$fetch() — для пользовательских действий (POST, PUT) или клиентских операций, не для данных, которые должны прийти с SSR.
Ленивая загрузка: lazy: true, useLazyFetch(), useLazyAsyncData() — для некритичных данных. Обрабатывайте status === 'pending' в UI.
server: false — только если данные не нужны для SEO и первого отображения.
pick — сокращайте размер 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 }
)

🗺️ Правила маршрутов (Route Rules)

В nuxt.config.ts задаются стратегии рендеринга для групп маршрутов:

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.

🐌 Ленивая загрузка и производительность

Nuxt уже делает code-splitting по маршрутам. Не дробите компоненты без нужды.
Используйте Lazy-префикс для динамического импорта неключевых компонентов: <LazyHeavyWidget />.
Комбинируйте с v-if, чтобы код загружался только когда компонент действительно нужен.
Отложенная гидратация (deferred hydration): <LazyProductGallery hydrate-on-visible /> — компонент гидратируется только когда появляется в области видимости.
Для кастомных стратегий — defineLazyHydrationComponent() с триггерами visible или idle.
Используйте NuxtLink для внутренних переходов — Nuxt предзагрузит компоненты и payload.

✅ Когда использовать

Гидратационные ошибки — несоответствие серверного и клиентского HTML.
Разные стратегии рендеринга — часть страниц статическая, часть динамическая, часть только на клиенте.
Оптимизация производительности — большие компоненты ниже сгиба экрана, тяжёлые виджеты, комментарии, графики.
Работа с данными — нужно получать данные на сервере и избегать двойных запросов.
Настройка кеширования — для API или страниц с разной свежестью.

⚠️ Важно знать

Ключи useAsyncData должны быть стабильными (строки или функции, возвращающие строку). Иначе кеш не работает, и данные будут перезапрашиваться.
Побочные эффекты в обработчиках useAsyncData недопустимы — они могут выполняться и на сервере, и на клиенте.
hydrate-on-visible и другие директивы отложенной гидратации работают только в Nuxt 4 (или с экспериментальным флагом в Nuxt 3).
Route Rules применяются по принципу «первое совпадение» — порядок в конфиге важен.
Проверочный список перед деплоем: одинаковый HTML, данные через useFetch/useAsyncData, ленивые данные с UI загрузки, корректные routeRules, тяжёлые компоненты ленивые или отложенные.

Установите одной командой.

npx skillfish add affaan-m/everything-claude-code nuxt4-patterns

Источник: https://mcpmarket.com/tools/skills/nuxt-4-patterns-optimization