Skip to content
Skills Library
Programming · Building & coding

nuxt4-patterns

/nuxt4-patterns

Nuxt 4 应用模式,涵盖水合安全、性能、路由规则、懒加载和使用 useFetch 和 useAsyncData 的 SSR 安全数据获取。

Licence
MIT
Last repository change
21.06.2026

Assessment and security

96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Nuxt 4 应用模式,涵盖水合安全、性能、路由规则、懒加载和使用 useFetch 和 useAsyncData 的 SSR 安全数据获取。

Original author description

Nuxt 4 应用模式,涵盖水合安全、性能、路由规则、懒加载和使用 useFetch 和 useAsyncData 的 SSR 安全数据获取。

How it works

  1. 何时使用
  2. 水合安全
  3. 数据获取
  4. 路由规则
  5. 懒加载和性能
  6. 审查清单
Original SKILL.md headings · 96 lines, 287 words
SKILL.md preview
---
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` 修剪负载大小,当深度反应性不必要时优先使用较浅的负载。

```ts
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` 进行渲染和缓存策略:

```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 级响应行为

按路由组选择路由规则,而不是全局。营销页面、目录、仪表板和 API 通常需要不同的策略。

## 懒加载和性能

- Nuxt 已经按路由拆分了页面代码。在微观优化组件拆分之前保持路由边界有意义。
- 使用 `Lazy` 前缀动态导入非关键组件。
- 使用 `v-if` 有条件地渲染懒组件,以便在 UI 实际需要之前不加载块。
- 对以下内容或非关键交互 UI 使用懒水合。

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

- 对于自定义策略,使用 `defineLazyHydrationComponent()` 配合可见性或空闲策略。
- Nuxt 懒水合适用于单文件组件。将新 props 传递给懒水合组件将立即触发水合。
- 使用 `NuxtLink` 进行内部导航,以便 Nuxt 可以预取路由组件和生成的负载。

## 审查清单

- 第一次 SSR 渲染和水合的客户端渲染产生相同的标记
- 页面数据使用 `useFetch` 或 `useAsyncData`,而不是顶级 `$fetch`
- 非关键数据是懒加载的,并具有显式加载 UI
- 路由规则与页面的 SEO 和新鲜度要求匹配
- 繁重的交互式岛屿是懒加载或懒水合的

Versions

RepositoryScoreLicence
This page · aaione/everything-claude-code-zh96MIT
affaan-m/ECC100MIT
SHRIJANAGAIN/Nemo-Cli100Apache-2.0
affaan-m/ECC96MIT

Database snapshot: 13.11.2026 · package version 1a808e7fe27d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100nuxt-data
    Nuxt 5 data management with useFetch, useAsyncData, useState, and Pinia. Use when creating composables, fetching data, managing state, or debugging reactive/SSR data issues.
  • 95nuxt-data
    | Nuxt 4 data management: composables, data fetching with useFetch/useAsyncData, and state management with useState and Pinia. Use when: creating custom composables, fetching data with useFetch or useAsyncData, managing global state with useState, integrating Pinia, debugging…
  • 90vue-nuxt
    Use this skill when the user says 'Nuxt', 'Nuxt 3', 'Nuxt structure', 'Nuxt composables', 'Nuxt server routes', 'useFetch', 'useAsyncData', 'Nuxt layers', 'Nuxt architecture', or when building a Nuxt 3 application. This skill enforces: directory-based routing in pages/, useFetch…
  • 90fe-nuxt
    Writes and reviews Nuxt 4 apps - useFetch and useAsyncData vs $fetch, keys, per-request state, server-safe setup, runtime config, route announcements - so pages render on the server without leaks, double requests or hydration errors. Use when editing files in a Nuxt project…
  • 100nuxt
    Nuxt is the full-stack Vue framework with server-side rendering, auto-imports, file-based routing and a Nitro server for API routes. Use it when a user asks to build or fix a Nuxt app, set up per-route rendering (SSR, prerender, ISR, SPA), fetch data with useFetch or…
  • 100nuxt
    Covers Nuxt across supported versions (3.x and 4.x): the Nitro server engine, auto-imports, file-based routing, data fetching (useFetch, useAsyncData, $fetch), hybrid rendering (SSR/SSG/ISR/SPA), modules ecosystem, server routes with H3, runtime config, TypeScript, Nuxt…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.