Everything Claude Code 的 nuxt4-patterns Skill 是专为 Nuxt 4 SSR/混合渲染项目设计的 AI 编程助手技能，聚焦 Hydration 安全、Route Rules 策略、SSR-safe useFetch/useAsyncData 数据获取和懒加载性能优化等核心场景。通过该 Skill，AI Agent 能自动识别并修复常见的服务端/客户端渲染不一致、数据获取重复、路由缓存失效和页面性能瓶颈问题，大幅提升 Nuxt 4 项目的开发效率与生产稳定性。

Everything Claude Code Nuxt 4 Patterns Skill：Hydration 安全、Route Rules、SSR-safe useFetch 最佳实践

在 Nuxt 4 项目中，SSR、混合渲染、路由规则和数据获取模式的正确实现直接决定了应用的性能、SEO 和开发体验。Everything Claude Code 的 nuxt4-patterns Skill，正是为了解决这些高频痛点而设计：它让 AI Agent 在构建、调试 Nuxt 4 应用时，自动应用业界最佳实践，规避常见陷阱，实现生产级的 SSR 安全和性能优化。

本指南将带你系统掌握 nuxt4-patterns Skill 的激活场景、操作流程、输出效果、常见配套 Agent 及与其他 Skill 的协作方式。无论你是初次接触 Nuxt 4，还是希望深度定制 AI 编程助手，都能借助该 Skill 实现高质量、高效率的开发闭环。

---

1. nuxt4-patterns Skill 能解决什么问题？

没有该 Skill 时，常见问题包括：

• SSR 首屏与客户端 Hydration 不一致，导致页面闪烁、警告或功能失效
• 路由级别的渲染策略混乱，SEO/缓存/性能难以兼顾
• useFetch/useAsyncData 用法不规范，导致数据重复获取、payload 过大或缓存失效
• 组件和页面懒加载策略混乱，影响首屏速度和交互体验

有了 nuxt4-patterns Skill，AI Agent 能自动：

• 检测并修复 SSR/客户端 Hydration 不一致的代码模式
• 推荐并生成合适的 routeRules 配置，实现静态化、SWR、ISR、纯客户端等路由策略分组
• 指导 useFetch/useAsyncData 的 SSR-safe 用法，避免重复请求与副作用
• 优化组件懒加载和懒 Hydration，减少无效资源加载和首屏阻塞

---

2. 触发条件与激活时机

nuxt4-patterns Skill 会在以下场景自动激活：

• 你在 Claude Code、Codex、Cursor 等 AI 编程助手中，询问 Nuxt 4 SSR、数据获取、路由渲染、性能优化相关问题时
• Agent 检测到项目存在 SSR Hydration mismatch、useFetch 用法不规范、routeRules 缺失或懒加载策略不合理时
• 结合 Everything Claude Code Rules 体系 或 Code Reviewer Agent 进行项目审查时，发现 Nuxt 4 相关代码片段

典型触发语句示例：

• “为什么我的 Nuxt 4 页面 SSR 后客户端刷新会报 hydration mismatch？”
• “如何为 /products 路由配置 SWR 或 ISR 策略？”
• “useFetch 和 useAsyncData 在 SSR 下怎么用才不会重复请求？”
• “怎么让非关键组件懒加载并延迟 hydration？”

---

3. Step by Step：nuxt4-patterns Skill 实战流程

步骤 1：识别 Hydration 安全风险

AI Agent 会自动检查：

• 是否在 SSR 模板中直接调用 Date.now()、Math.random()、浏览器 API 或本地存储
• 是否有仅客户端可用的逻辑未包裹在 onMounted()、import.meta.client、ClientOnly 或 .client.vue 组件内
• 是否错误使用了 vue-router 的 useRoute 而非 Nuxt 的 useRoute

修正建议示例：

<script setup>
import { onMounted } from 'vue'

const now = ref(0)
onMounted(() => {
  now.value = Date.now()
})
</script>

步骤 2：规范 SSR-safe 数据获取

推荐用法：

• 页面和组件级数据获取优先用 await useFetch()，这样 SSR 阶段获取的数据会自动注入 Nuxt payload，避免 hydration 时重复请求
• 复杂异步/多源数据用 useAsyncData()，需自定义稳定的 key，保证缓存和刷新行为可控
• 仅在用户主动触发或纯客户端场景下用 $fetch()

代码示例：

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, // 只在客户端获取，非首屏/SEO 关键数据
})

步骤 3：为路由分组配置 Route Rules

AI Agent 会根据页面类型自动推荐 routeRules：

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true }, // 首页静态化
    '/products/**': { swr: 3600 }, // 商品页 SWR 缓存
    '/blog/**': { isr: true }, // 博客增量静态生成
    '/admin/**': { ssr: false }, // 后台仅客户端渲染
    '/api/**': { cache: { maxAge: 60 * 60 } }, // API 缓存
  },
})

每类页面采用不同策略，兼顾性能、SEO 和内容时效性。

步骤 4：优化懒加载与懒 Hydration

• Nuxt 默认已按路由分割代码，建议优先优化路由边界
• 非关键组件用 Lazy 前缀动态导入，配合 v-if 条件渲染，避免无效 chunk 加载
• 使用 hydrate-on-visible 等懒 hydration 属性，提升首屏速度
• 对于更复杂的场景，可用 defineLazyHydrationComponent() 自定义懒 hydration 策略

模板示例：

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

---

4. 输出效果与预期结果

应用 nuxt4-patterns Skill 后，AI Agent 输出将包含：

• SSR/客户端一致的安全代码片段和组件结构
• 精确匹配业务需求的 routeRules 配置代码及解释
• useFetch/useAsyncData 的标准用法及缓存/懒加载建议
• 懒加载组件与懒 hydration 的具体实现方式
• 针对当前项目的最佳实践清单与检查表，便于团队落地

---

5. 常见配套 Agent 与 Skill 协作

• Code Reviewer Agent：结合 nuxt4-patterns Skill 自动审查 SSR、数据获取和路由配置，输出修复建议
• Performance Optimizer Agent：检测页面/组件性能瓶颈，配合懒加载与 SSR-safe 数据获取模式优化首屏
• Rules 体系：通过 Nuxt 4 相关规则集，约束项目成员统一最佳实践
• Frontend Patterns Skill：跨 React/Next.js/Nuxt 等前端框架共享通用模式

---

FAQ

Q: nuxt4-patterns Skill 能自动修复 SSR hydration mismatch 吗？
A: 可以，AI Agent 会识别 SSR/客户端不一致的代码模式，并推荐用 onMounted、ClientOnly 等安全包裹方式。

Q: useFetch 和 useAsyncData 在 Nuxt 4 SSR 下怎么选？
A: useFetch 适合简单 API 读取，自动注入 payload；useAsyncData 适合复杂异步和自定义缓存 key 场景，两者都能 SSR 安全获取数据。

Q: 路由规则（routeRules）配置有推荐模板吗？
A: Skill 会根据页面类型自动输出 routeRules 示例，并解释 prerender、swr、isr、ssr: false 等策略如何应用于不同路由分组。

---