Nuxt.js 深度解析

┌─────────────────────────────────────────────────────────┐
│                    开发者代码层                           │
│   pages/  layouts/  components/  server/  plugins/      │
├─────────────────────────────────────────────────────────┤
│                    Nuxt 框架层                           │
│   Nuxt Core · Nuxt Kit · @nuxt/schema                   │
│   自动导入 · 模块系统 · 插件系统 · 中间件系统              │
├─────────────────────────────────────────────────────────┤
│                    引擎层                                │
│   Nitro (Server Engine)  ·  Vite (Build Engine)         │
│   h3 (HTTP Framework)   ·  vue-bundle-renderer         │
├─────────────────────────────────────────────────────────┤
│                    平台/运行时层                          │
│   Node.js · Cloudflare Workers · Deno · Vercel Edge     │
│   AWS Lambda · Netlify Functions · Static Hosting       │
└─────────────────────────────────────────────────────────┘

用户执行 nuxi dev
       │
       ▼
  CLI 入口 (nuxi)
       │
       ▼
  加载 nuxt.config.ts
  (使用 jiti 执行 TypeScript 配置文件)
       │
       ▼
  创建 Nuxt 实例
  (调用 createNuxt(options))
       │
       ▼
  ┌─────────────────────────┐
  │  Nuxt 实例内部结构       │
  │  - options (完整配置)    │
  │  - hooks (钩子系统)      │
  │  - vfs (虚拟文件系统)    │
  │  - server (Nitro引用)    │
  └─────────────────────────┘
       │
       ▼
  安装所有模块 (installModules)
  按 nuxt.config 中 modules 数组的顺序
  依次调用每个模块的 setup()
       │
       ▼
  执行 Nuxt 钩子
  (modules:done → app:resolve → build:before → ...)
       │
       ▼
  扫描项目目录
  (pages/, components/, composables/, plugins/, middleware/)
       │
       ▼
  生成 .nuxt/ 虚拟文件
  (路由表、插件注册、组件注册等)
       │
       ▼
  启动开发服务器 (Vite dev server + Nitro dev server)
  或执行生产构建 (Vite build + Nitro build)

// H3Event —— 封装了每个 HTTP 请求的上下文
interface H3Event {
  // 底层的 Node.js 请求/响应对象（Node.js 环境）
  node: {
    req: IncomingMessage
    res: ServerResponse
  }
  // Web Standards 的 Request/Response（跨平台环境）
  web?: {
    request: Request
  }
  // 请求上下文，可以存储任意数据
  context: Record<string, any>
  // 请求的 Fetch API Request 对象
  _request?: Request
}

// 读取请求体
const body = await readBody(event)       // JSON body
const formData = await readFormData(event) // form data
const rawBody = await readRawBody(event)   // raw buffer

// 读取查询参数
const query = getQuery(event)            // ?key=value → { key: 'value' }

// 读取路由参数
const params = getRouterParams(event)    // /api/user/:id → { id: '...' }

// 设置响应头/状态码
setResponseHeader(event, 'Content-Type', 'application/json')
setResponseStatus(event, 201)

// 发送响应
return { data: '...' }                   // 自动 JSON 序列化
return send(event, 'Hello')             // 发送字符串
return sendStream(event, readableStream) // 流式响应

// 错误处理
throw createError({
  statusCode: 404,
  statusMessage: 'Not Found',
  data: { id: '...' }
})

server/
├── api/                    # API 路由（自动注册为 /api/* 端点）
│   ├── hello.ts            # GET /api/hello
│   ├── hello.post.ts       # POST /api/hello（通过文件名后缀指定 HTTP 方法）
│   └── users/
│       ├── index.ts        # GET /api/users
│       ├── [id].ts         # GET /api/users/:id（动态路由参数）
│       └── [id].put.ts     # PUT /api/users/:id
├── routes/                 # 自定义路由（不自动加 /api 前缀）
│   └── health.ts           # GET /health
├── middleware/              # 服务器中间件（在每个请求前执行）
│   ├── auth.ts             # 认证中间件
│   └── logger.ts           # 日志中间件
├── plugins/                # Nitro 插件（服务器启动时执行一次）
│   └── database.ts         # 数据库连接初始化
└── utils/                  # 服务器工具函数（自动导入）
    └── validators.ts

// server/api/hello.ts
export default defineEventHandler(async (event: H3Event) => {
  // event 是 h3 的事件对象，包含了请求的所有信息

  // 读取查询参数
  const query = getQuery(event)

  // 读取请求体
  const body = await readBody(event)

  // 返回数据（自动序列化为 JSON）
  return {
    message: 'Hello World',
    query
  }
})

// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  // 中间件可以修改 event.context，后续的处理函数可以读取
  event.context.userId = await verifyToken(getHeader(event, 'Authorization'))

  // 如果中间件返回了值，就直接作为响应返回，不再执行后续处理
  // 如果不返回值（return undefined），则继续执行后续处理
})

.output/
├── server/
│   ├── index.mjs           # 服务器入口（可直接 node index.mjs 启动）
│   ├── chunks/             # 代码分割后的 chunk 文件
│   └── plugins/            # Nitro 插件
├── public/                 # 静态资源
│   ├── _nuxt/              # 客户端构建产物（JS/CSS/字体等）
│   ├── favicon.ico
│   └── ...
├── nitro.json              # Nitro 元数据
└── package.json            # 精简的 package.json（只包含运行时依赖）

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // 这个页面使用 SPA 模式（不 SSR）
    '/admin/**': { ssr: false },

    // 这个页面静态生成（构建时生成 HTML）
    '/blog': { prerender: true },

    // 这个 API 使用 ISR（增量静态再生成），缓存 1 小时
    '/api/popular': { isr: 3600 },

    // 这个页面使用 SWR（stale-while-revalidate），缓存 10 分钟
    '/products/**': { swr: 600 },

    // 这个路径重定向
    '/old-page': { redirect: '/new-page' },

    // 添加自定义响应头
    '/api/**': {
      headers: { 'X-Custom-Header': 'value' }
    }
  }
})

浏览器加载 HTML
       │
       ▼
  加载客户端 JS Bundle
       │
       ▼
  执行 Nuxt 入口文件
  (.nuxt/dist/client/app.config.mjs → nuxt/dist/app/)
       │
       ▼
  创建 Vue App 实例
  (createApp() 或 createSSRApp())
       │
       ▼
  创建 NuxtApp 实例
  (运行时 NuxtApp，包含插件、钩子、payload 等)
       │
       ▼
  安装 Vue 插件
  (router、pinia、全局组件等)
       │
       ▼
  执行 Nuxt 插件
  (按顺序执行 plugins/ 目录下的插件)
       │
       ▼
  挂载 Vue App 到 DOM
  (app.mount('#__nuxt'))
       │
       ▼
  水合（Hydration）
  (将服务端渲染的静态 HTML "激活"为可交互的 Vue 应用)

interface NuxtApp {
  // Vue 应用实例
  vueApp: App<Element>

  // 全局属性（类似 Vue 2 的 Vue.prototype）
  globalName: string   // 默认 'nuxt'

  // 版本信息
  versions: Record<string, string>

  // 钩子系统
  hooks: Hookable<NuxtAppHooks>
  hook: NuxtApp['hooks']['hook']
  callHook: NuxtApp['hooks']['callHook']

  // 运行回调（注册在 app 挂载/渲染时执行的回调）
  _asyncDataPromises: Record<string, Promise<any>>

  // SSR 上下文（仅在服务端存在）
  ssrContext?: NuxtSSRContext

  // Payload（服务端传递给客户端的数据）
  payload: {
    serverRendered: boolean
    data: Record<string, any>
    state: Record<string, any>
    error?: Error | { url: string, statusCode: number, statusMessage: string }
    _errors: Record<string, any>
    [key: string]: any
  }

  // 是否在水合阶段
  isHydrating: boolean

  // 提供/注入（类似 Vue 的 provide/inject，但在 NuxtApp 层面）
  provide: (name: string, value: any) => void

  // 内部属性
  _scope: EffectScope
  _id: number
  _processingPlugin: boolean
}

interface NuxtSSRContext {
  // 当前请求的 URL
  url: string

  // 请求的事件对象（h3 的 H3Event）
  event: H3Event

  // 请求的来源（IP、Host 等）
  req: IncomingMessage  // Node.js 环境
  res: ServerResponse   // Node.js 环境

  // 渲染结果
  noSSR: boolean          // 是否跳过 SSR
  error?: any             // SSR 过程中的错误

  // 渲染过程中的数据收集
  payload: {
    data: Record<string, any>    // useAsyncData 的缓存
    state: Record<string, any>   // useState 的缓存
    _errors: Record<string, any>
  }

  // 用于 <head> 标签管理（useHead）
  head: HeadEntry[]

  // 组件渲染追踪
  renderedComponents?: Set<string>

  // 岛屿组件相关
  islands: Map<string, any>

  // 渲染出的 HTML
  renderResult?: {
    html: string
  }

  // 缓存和去重
  _asyncDataPromises: Record<string, Promise<any>>

  // Teleports（Vue 的 <Teleport> 组件渲染结果）
  teleports: Record<string, string>
}

<!-- pages/index.vue -->
<script setup>
definePageMeta({
  layout: 'default',         // 使用哪个布局
  middleware: ['auth'],      // 使用哪些中间件
  // 路由元信息
  pageType: 'home',
  requiresAuth: false,
  // 过渡动画
  pageTransition: { name: 'page', mode: 'out-in' },
  layoutTransition: { name: 'layout', mode: 'out-in' },
  // keep-alive
  keepalive: true,
  // 自定义滚动行为
  scrollToTop: true
})
</script>

<!-- layouts/default.vue -->
<template>
  <div>
    <AppHeader />
    <main>
      <slot />   <!-- 页面内容在这里渲染 -->
    </main>
    <AppFooter />
  </div>
</template>

<NuxtLayout>            ← 最外层布局
  └── <NuxtPage>       ← 页面组件
        └── <NuxtLayout>  ← 如果页面内部又有布局（嵌套路由场景）
              └── <NuxtPage>  ← 子路由页面

<NuxtLink to="/about" prefetch>关于我们</NuxtLink>
<NuxtLink to="/products" :prefetch="false">产品</NuxtLink>
<NuxtLink to="https://example.com">外部链接</NuxtLink>

① 浏览器发送 HTTP 请求 → https://example.com/products

② Nitro 服务器接收请求
   - h3 路由匹配 → 进入 SSR 渲染处理器
   - 检查 Route Rules：该路径是否配置了 SSR？
   - 创建 NuxtSSRContext

③ Vue SSR 渲染
   - 创建 Vue 应用实例（createSSRApp）
   - 安装路由，设置当前 URL
   - 安装所有 Nuxt 插件
   - 执行页面组件的 setup()
     → useAsyncData() / useFetch() 被调用
     → 在服务端发起数据请求
     → 数据存入 NuxtSSRContext.payload.data
   - Vue 渲染器将虚拟 DOM 渲染为 HTML 字符串
     (使用 vue-bundle-renderer 的 renderToString)
   - 收集渲染过程中触发的 <Head> 标签
   - 收集 <Teleport> 内容

④ 组装完整 HTML
   Nitro 将各部分拼接：

   <!DOCTYPE html>
   <html>
   <head>
     <!-- 来自 useHead() 的标签 -->
     <title>Products</title>
     <meta name="description" content="..." />
     <link rel="stylesheet" href="/_nuxt/xxx.css" />
   </head>
   <body>
     <div id="__nuxt">
       <!-- SSR 渲染出的 HTML -->
       <div class="products-page">
         <h1>Products</h1>
         <ul>
           <li>Product 1 - $99</li>
           <li>Product 2 - $199</li>
         </ul>
       </div>
     </div>

     <!-- Payload 注入脚本 -->
     <script>
       window.__NUXT__ = {
         data: { "products-page": { data: [...], pending: false } },
         state: { ... },
         serverRendered: true,
         config: { ... }
       }
     </script>

     <script type="module" src="/_nuxt/entry.js"></script>
   </body>
   </html>

⑤ 返回 HTML 给浏览器

⑥ 浏览器渲染 HTML
   - 用户立即看到页面内容（有内容但不可交互）
   - 同时下载客户端 JS Bundle

⑦ 客户端 JS 执行
   - 创建 Vue 应用实例（createSSRApp）
   - 读取 window.__NUXT__ 中的 payload
   - 使用 payload 中的数据初始化 useAsyncData 缓存
     （避免客户端再次请求相同数据）
   - 执行水合（Hydration）：
     Vue 将已有的 DOM 与虚拟 DOM 进行匹配，
     添加事件监听器，激活响应式系统

⑧ 页面变为可交互状态（Interactive）

<!-- 方案1：使用 ClientOnly -->
<ClientOnly>
  <ClientSideOnlyComponent />
</ClientOnly>

<!-- 方案2：使用 onMounted 延迟渲染 -->
<script setup>
const isClient = ref(false)
onMounted(() => { isClient.value = true })
</script>
<template>
  <div v-if="isClient">{{ new Date().toLocaleString() }}</div>
  <div v-else>Loading time...</div>
</template>

<!-- 方案3：使用 useHydration 的友好方式 -->
<script setup>
const nuxtApp = useNuxtApp()
// nuxtApp.isHydrating 为 true 时，说明正在水合
</script>

① 用户点击 <NuxtLink to="/about">

② NuxtLink 拦截点击事件
   - 调用 vue-router 的 push()
   - URL 变为 /about（History API）

③ Nuxt 客户端路由守卫触发
   - 执行全局中间件（middleware/）
   - 执行页面级中间件（definePageMeta 中的 middleware）
   - 如果中间件调用了 navigateTo() 或 abortNavigation()，导航中止

④ 加载目标页面的 JS chunk
   - 如果该 chunk 还没有加载，动态 import()
   - 这就是为什么 Nuxt 页面是自动代码分割的

⑤ 执行目标页面的 setup()
   - useAsyncData() / useFetch() 被调用
   - 如果 payload 中已有该页面的数据（通过 prefetch），直接使用
   - 否则发起 API 请求获取数据

⑥ 渲染新页面组件
   - 触发页面过渡动画（如果有配置）
   - Vue 更新 DOM

⑦ 页面更新完成

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false  // 全局关闭 SSR
})
// 或者通过 Route Rules 对特定路由关闭

// nuxt.config.ts
export default defineNuxtConfig({
  // 构建时使用 SSR 渲染每个路由，生成静态 HTML
  // 运行时不需要 Node.js 服务器
})
// 执行 npx nuxi generate

routeRules: {
  '/blog/**': { isr: 3600 }  // 每小时重新生成
}

<template>
  <div>
    <!-- 这个组件在服务端渲染，不在客户端水合 -->
    <StaticContent />

    <!-- 这个组件在服务端渲染，并在客户端水合（可交互） -->
    <NuxtIsland name="InteractiveChart" :props="{ data }" />
  </div>
</template>

// 签名
function useAsyncData<T>(
  key: string,                          // 唯一标识符
  handler: () => Promise<T>,            // 数据获取函数
  options?: AsyncDataOptions<T>         // 配置项
): AsyncData<T>

function useAsyncData<T>(
  handler: () => Promise<T>,            // key 可以省略（自动基于文件路径生成）
  options?: AsyncDataOptions<T>
): AsyncData<T>

interface AsyncData<T> {
  data: Ref<T | null>           // 数据（响应式引用）
  pending: Ref<boolean>         // 加载状态
  status: Ref<'idle' | 'pending' | 'success' | 'error'>
  error: Ref<Error | null>      // 错误信息
  refresh: () => Promise<void>  // 手动刷新数据
  execute: () => Promise<void>  // 手动执行数据获取
  clear: () => void             // 清除数据
}

interface AsyncDataOptions<T> {
  server?: boolean          // 是否在服务端执行（默认 true）
  lazy?: boolean            // 是否懒加载（默认 false）
  default?: () => T | Ref<T>  // 默认值
  transform?: (data: T) => T   // 数据转换函数
  pick?: string[]           // 数据选取函数
  watch?: Ref[]             // 响应式值变化时自动重新获取
  immediate?: boolean       // 是否立即执行（默认 true）
  deep?: boolean            // 深度监听（默认 true）
  dedupe?: 'cancel' | 'defer'  // 去重策略
}

useAsyncData(key, handler) 被调用
       │
       ▼
  检查 NuxtApp._asyncDataPromises[key]
  是否已有相同 key 的进行中请求？
       │
       ├── 有 → 复用已有的 Promise（去重）
       │
       └── 没有 →
              │
              ▼
         检查 NuxtApp.payload.data[key]
         服务端是否已经获取了数据？（SSR payload）
              │
              ├── 有 → 直接使用 payload 中的数据
              │         不调用 handler
              │         data.value = payload.data[key]
              │
              └── 没有 →
                     │
                     ▼
                  检查当前环境
                     │
                     ├── 服务端（SSR）
                     │   → 调用 handler()
                     │   → 结果存入 payload.data[key]
                     │   → 会被序列化到 HTML 中
                     │
                     └── 客户端
                         → 调用 handler()
                         → 结果存入 data.value
                         → 不进入 payload

// 签名
function useFetch<T>(
  url: string | Ref<string> | (() => string),  // URL（可以是响应式的）
  options?: UseFetchOptions<T>
): AsyncData<T>

interface UseFetchOptions<T> extends AsyncDataOptions<T> {
  method?: string          // 请求方法
  query?: Record<string, any>   // 查询参数
  params?: Record<string, any>  // URL 路径参数
  body?: any               // 请求体
  headers?: Record<string, string>  // 请求头
  baseURL?: string          // 基础 URL
  onResponse?: (context: { response: Response }) => void
  onResponseError?: (context: { response: Response }) => void
  onRequest?: (context: { request: Request, options: any }) => void
  onRequestError?: (context: { request: Request, options: any, error: Error }) => void
  transform?: (data: any) => T
  pick?: string[]
  timeout?: number
}

// 基本用法
const { data, pending, error, refresh } = await useFetch('/api/products')

// 带参数
const { data } = await useFetch('/api/products', {
  method: 'POST',
  body: { category: 'electronics' },
  query: { page: 1, limit: 20 }
})

// URL 响应式（URL 变化时自动重新获取）
const id = ref(1)
const { data } = await useFetch(() => `/api/products/${id.value}`)

// watch 触发重新获取
const search = ref('')
const { data } = await useFetch('/api/search', {
  query: { q: search },
  watch: [search]
})

// transform + pick
const { data } = await useFetch('/api/users', {
  transform: (response) => response.data,
  pick: ['name', 'email']
})

// 在服务端：
// - 如果请求的是本站 API（如 /api/xxx），直接调用 Nitro 处理函数
//   不发起真实的 HTTP 请求（零网络开销！）
// - 如果请求的是外部 URL，发起真实的 HTTP 请求

// 在客户端：
// - 总是发起真实的 HTTP 请求（fetch API）

// 用法
const data = await $fetch('/api/users', {
  method: 'GET',
  query: { page: 1 },
  headers: { Authorization: 'Bearer xxx' }
})

// 注意：$fetch 不会自动处理 SSR 数据同步
// 如果需要 SSR 兼容，应该用 useFetch 或 useAsyncData + $fetch

┌──────────────────────────────────────┐
│         Nitro 服务器进程              │
│                                      │
│  SSR 渲染器                          │
│    │                                 │
│    ├── useFetch('/api/products')     │
│    │     │                           │
│    │     ▼                           │
│    │   $fetch 检测到是本站 API        │
│    │     │                           │
│    │     ▼                           │
│    │   直接调用 API handler 函数      │
│    │   （不经过网络层，零开销）        │
│    │     │                           │
│    │     ▼                           │
│    │   server/api/products.ts        │
│    │   的 default export 被直接调用   │
│    │                                 │
│  server/api/products.ts              │
│    └── defineEventHandler(...)       │
└──────────────────────────────────────┘

// 签名
function useCookie<T = string | null>(
  name: string,
  options?: CookieOptions
): Ref<T | null>

interface CookieOptions {
  path?: string          // 默认 '/'
  domain?: string
  maxAge?: number         // 秒
  expires?: Date
  httpOnly?: boolean
  secure?: boolean
  sameSite?: 'strict' | 'lax' | 'none' | boolean
  default?: () => T       // 默认值
  watch?: boolean | 'shallow'
  readonly?: boolean
}

// 基本用法
const token = useCookie('auth-token')
token.value = 'new-jwt-token'  // 自动写入 Cookie

// 带默认值和类型
const theme = useCookie<'light' | 'dark'>('theme', {
  default: () => 'light',
  maxAge: 60 * 60 * 24 * 365  // 1年
})

// 存储复杂数据（自动 JSON 序列化/反序列化）
const preferences = useCookie('user-prefs', {
  default: () => ({ sidebar: true, compact: false })
})

// useRequestHeaders —— 获取当前 SSR 请求的请求头
const headers = useRequestHeaders()                    // 所有请求头
const cookies = useRequestHeaders(['cookie'])           // 只要 cookie 头
const authHeaders = useRequestHeaders(['authorization']) // 只要 auth 头

// useRequestFetch —— 创建一个自动转发 SSR 请求头的 $fetch
const fetch = useRequestFetch()
const { data } = await useAsyncData('user', () =>
  fetch('/api/auth/me')  // 自动携带 SSR 请求的 Cookie
)

// composables/useAuth.ts
export const useAuth = () => {
  const fetch = useRequestFetch()

  const { data: user } = await useAsyncData('user', () =>
    fetch('/api/auth/me').catch(() => null)
  )

  return { user, isLoggedIn: computed(() => !!user.value) }
}

// server/api/cache.ts
export default defineEventHandler(async (event) => {
  const storage = useStorage()

  await storage.setItem('cache:key', { data: 'value' })
  const value = await storage.getItem('cache:key')

  await storage.setItem('redis:user:123', userData)

  return value
})

// nuxt.config.ts —— 配置存储驱动
export default defineNuxtConfig({
  nitro: {
    storage: {
      cache: { driver: 'memory' },
      redis: {
        driver: 'redis',
        host: process.env.REDIS_HOST,
        port: 6379
      },
      files: {
        driver: 'fs',
        base: './data'
      }
    }
  }
})

// 签名
function useState<T>(
  key: string,                  // 唯一标识符
  init?: () => T | Ref<T>      // 初始值工厂函数
): Ref<T>

// composables/useCounter.ts
export const useCounter = () => {
  const count = useState('counter', () => 0)
  const increment = () => count.value++
  const decrement = () => count.value--
  return { count, increment, decrement }
}

// stores/auth.ts
export const useAuthStore = defineStore('auth', () => {
  const user = ref(null)
  const isLoggedIn = computed(() => !!user.value)

  async function login(credentials) {
    user.value = await $fetch('/api/auth/login', {
      method: 'POST',
      body: credentials
    })
  }

  function logout() {
    user.value = null
    navigateTo('/login')
  }

  return { user, isLoggedIn, login, logout }
})

// composables/useProducts.ts
export const useProducts = () => {
  return useAsyncData('products', () => $fetch('/api/products'))
}

// 在组件 A 中
const { data: products } = await useProducts()
// 在组件 B 中
const { data: products } = await useProducts()
// 两个组件共享同一份数据，只发起一次请求

// plugins/myPlugin.ts

// 方式1：简单函数
export default defineNuxtPlugin((nuxtApp) => {
  // nuxtApp 是运行时的 NuxtApp 实例
  // nuxtApp.vueApp.use(someVuePlugin)
  nuxtApp.provide('myHelper', () => { /* ... */ })
})

// 方式2：对象形式（更精细的控制）
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',             // 执行时机：'pre' | 'default' | 'post'
  dependsOn: ['other-plugin'],
  async setup(nuxtApp) {
    // 插件逻辑
  },
  hooks: {
    'app:created'(vueApp) { /* ... */ },
    'page:start'() { /* ... */ }
  }
})

// 通过文件名控制环境：
// plugins/myPlugin.client.ts  → 只在客户端执行
// plugins/myPlugin.server.ts  → 只在服务端执行

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const authStore = useAuthStore()

  if (!authStore.isLoggedIn && to.meta.requiresAuth) {
    return navigateTo('/login')
  }

  // 不返回值 = 继续导航
  // 返回 navigateTo('/path') = 重定向
  // 返回 abortNavigation() = 中止导航
  // 返回 abortNavigation(error) = 中止并设置错误
})

// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  // 对每个 API 请求和 SSR 请求都会执行
  const token = getHeader(event, 'Authorization')
  if (token) {
    event.context.user = await verifyToken(token)
  }
  // 不返回值 = 继续处理
  // 返回值 = 直接响应，不再执行后续处理
})

// modules/myModule.ts
import { defineNuxtModule, addPlugin, addComponent, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
    compatibility: { nuxt: '>=3.0.0' }
  },
  defaults: {
    apiKey: '',
    enableFeature: true
  },
  async setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // 1. 注册插件
    addPlugin(resolver.resolve('./runtime/plugin'))

    // 2. 注册组件
    addComponent({
      name: 'MyComponent',
      filePath: resolver.resolve('./runtime/MyComponent.vue')
    })

    // 3. 注册 composable（使其可被自动导入）
    nuxt.hook('imports:dirs', (dirs) => {
      dirs.push(resolver.resolve('./runtime/composables'))
    })

    // 4. 注册服务器 API
    addServerHandler({
      route: '/api/my-module/data',
      handler: resolver.resolve('./runtime/server/api/data')
    })

    // 5. 修改 Nuxt 配置
    nuxt.options.css.push('my-module/dist/styles.css')

    // 6. 修改 Vite 配置
    nuxt.hook('vite:extendConfig', (config) => {
      config.resolve.alias['#my-module'] = resolver.resolve('./runtime')
    })

    // 7. 注册 Nitro 插件
    nuxt.hook('nitro:config', (nitroConfig) => {
      nitroConfig.plugins = nitroConfig.plugins || []
      nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugin'))
    })
  }
})

modules:before          ← 模块安装前
modules:done            ← 所有模块安装完成
app:resolve             ← Vue 应用配置解析完成
app:templates           ← 虚拟文件模板生成前
app:templatesGenerated  ← 虚拟文件生成完成
build:before            ← 构建开始前
build:done              ← 构建完成
pages:extend            ← 路由表生成后（可添加/修改路由）
components:extend       ← 组件列表生成后
imports:dirs            ← 自动导入目录收集
imports:extend          ← 自动导入列表生成后
nitro:config            ← Nitro 配置生成后
nitro:init              ← Nitro 实例创建后
vite:extendConfig       ← Vite 配置生成后
vite:serverCreated      ← Vite 开发服务器创建后

defineNuxtModule({ meta, defaults, setup })  // 定义模块
addPlugin({ src, mode })                       // 添加插件
addComponent({ name, filePath })               // 添加组件
addServerHandler({ route, handler, method, middleware })  // 添加服务器处理器
addServerPlugin({ src })                       // 添加服务器插件
addRouteMiddleware({ name, path, global })     // 添加路由中间件
extendPages((pages) => { pages.push(...) })    // 修改页面路由
extendViteConfig((config) => { ... })          // 修改 Vite 配置
extendWebpackConfig((config) => { ... })       // 修改 Webpack 配置
addVitePlugin(plugin)                          // 安装 Vite 插件
createResolver(import.meta.url)                // 创建路径解析器
useNuxt()                                      // 获取 Nuxt 实例
useLogger('my-module')                         // 创建日志

// 应用生命周期
app:beforeMount         // Vue 应用挂载前
app:mounted             // Vue 应用挂载完成
app:error               // 应用发生错误
app:suspense:resolve    // Suspense 解析完成

// 页面导航
page:start              // 页面导航开始
page:finish             // 页面导航完成
page:loading:start      // 页面加载开始
page:loading:end        // 页面加载结束
page:transition:finish  // 页面过渡动画完成

// 数据获取
asyncData:start         // useAsyncData 开始
asyncData:end           // useAsyncData 结束

// 渲染
app:rendered            // SSR 渲染完成（仅服务端）
app:chunkError          // 加载 JS chunk 失败

// 使用方式
const nuxtApp = useNuxtApp()
nuxtApp.hook('page:finish', () => {
  console.log('Page navigation finished')
})

// 请求生命周期
request            // 收到请求
beforeResponse     // 响应发送前
afterResponse      // 响应发送后
error              // 请求处理出错

// 渲染
render:html        // HTML 渲染后（可修改 HTML）
render:response    // 响应准备发送前

// 使用方式（在 Nitro 插件中）
// server/plugins/renderHook.ts
export default defineStritroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    // html 是一个对象，包含 head、bodyAppend 等数组
    html.head.push('<link rel="preconnect" href="https://fonts.googleapis.com" />')
  })
})

my-nuxt-app/
├── .nuxt/                    # 自动生成的虚拟文件（不要手动修改，加入 .gitignore）
├── .output/                  # 生产构建产物
├── app.vue                   # 应用根组件（入口组件）
├── app.config.ts             # 应用配置（可在运行时通过 payload 传递）
├── error.vue                 # 全局错误页面
├── nuxt.config.ts            # Nuxt 配置（构建时）
├── tsconfig.json             # TypeScript 配置
│
├── assets/                   # 静态资源（会被构建工具处理）
│   ├── css/
│   ├── images/
│   └── fonts/
│
├── public/                   # 公共资源（直接复制到输出目录）
│   ├── favicon.ico
│   └── robots.txt
│
├── components/               # Vue 组件（自动注册）
│   ├── AppHeader.vue         # → <AppHeader />
│   ├── AppFooter.vue         # → <AppFooter />
│   ├── ui/
│   │   ├── Button.vue        # → <UiButton />
│   │   └── Input.vue         # → <UiInput />
│   └── base/
│       └── Card.vue          # → <BaseCard />
│
├── composables/              # 组合式函数（自动导入）
│   ├── useAuth.ts
│   ├── useProducts.ts
│   └── useCounter.ts
│
├── utils/                    # 工具函数（自动导入）
│   ├── formatters.ts
│   └── validators.ts
│
├── layouts/                  # 页面布局
│   ├── default.vue
│   ├── auth.vue
│   └── blank.vue
│
├── pages/                    # 路由页面
│   ├── index.vue             # /
│   ├── about.vue             # /about
│   ├── products/
│   │   ├── index.vue         # /products
│   │   ├── [id].vue          # /products/:id（动态路由）
│   │   └── [...slug].vue     # /products/*（通配路由）
│   └── users/
│       ├── index.vue         # /users
│       └── [id]/
│           ├── index.vue     # /users/:id
│           └── settings.vue  # /users/:id/settings（嵌套路由）
│
├── middleware/                # 路由中间件
│   ├── auth.global.ts        # 全局中间件
│   └── admin.ts              # 命名中间件
│
├── plugins/                  # Nuxt 插件
│   ├── vue-plugins.ts
│   ├── analytics.client.ts   # 只在客户端执行
│   └── i18n.ts
│
├── server/                   # 服务器代码（Nitro）
│   ├── api/                  # API 路由
│   ├── routes/               # 自定义路由
│   ├── middleware/            # 服务器中间件
│   ├── plugins/              # Nitro 插件
│   └── utils/                # 服务器工具函数（自动导入）
│
├── stores/                   # Pinia stores
│   └── auth.ts
│
└── types/                    # TypeScript 类型定义
    └── index.d.ts

<!-- app.vue -->
<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>

<!-- error.vue -->
<script setup>
const props = defineProps(['error'])
const handleError = () => clearError({ redirect: '/' })
</script>
<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="handleError">返回首页</button>
  </div>
</template>

// app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#3b82f6',
    dark: false
  },
  siteName: 'My App'
})

// 在组件中使用
const appConfig = useAppConfig()
console.log(appConfig.theme.primaryColor)

// NuxtLink 的预取逻辑（简化）
class NuxtLinkPrefetch {
  // 1. 使用 IntersectionObserver 监听链接是否进入视口
  observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        this.prefetchRoute(entry.target.href)
      }
    })
  })

  // 2. 预取目标页面的 JS chunk
  async prefetchRoute(url) {
    // 动态 import() 页面组件
    // 浏览器会在后台下载但不执行
  }

  // 3. 可选：预取页面的数据
  async prefetchData(url) {
    // 提前调用 API 获取数据
  }
}

<NuxtImg
  src="/images/hero.jpg"
  width="800"
  height="400"
  format="webp"
  quality="80"
  loading="lazy"
  placeholder
/>

useHead({
  title: 'My Page Title',
  meta: [
    { name: 'description', content: 'Page description for SEO' },
    { property: 'og:title', content: 'My Page Title' },
    { property: 'og:image', content: 'https://example.com/image.jpg' }
  ],
  link: [
    { rel: 'canonical', href: 'https://example.com/page' }
  ],
  script: [
    { src: 'https://analytics.example.com/script.js', defer: true }
  ]
})

// 或者使用 useSeoMeta（更便捷的 SEO 元信息）
useSeoMeta({
  title: 'My Page',
  description: 'Page description',
  ogTitle: 'My Page',
  ogDescription: 'Page description',
  ogImage: 'https://example.com/image.jpg',
  twitterCard: 'summary_large_image'
})

# 构建
npx nuxi build

# 启动（生产）
PORT=3000 HOST=0.0.0.0 node .output/server/index.mjs

# 或使用 PM2
pm2 start .output/server/index.mjs --name my-nuxt-app

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/.output .output
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅在服务端可用
    apiSecret: process.env.API_SECRET,
    dbUrl: process.env.DATABASE_URL,

    // 在客户端和服务端都可用
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || 'https://api.example.com',
      appName: 'My Nuxt App'
    }
  }
})

// 在代码中使用
const config = useRuntimeConfig()
// 服务端：可以访问 config.apiSecret 和 config.public.apiBase
// 客户端：只能访问 config.public.apiBase

// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  // 自动设置 Nuxt 测试环境
})

// components/__tests__/Button.spec.ts
import { mountSuspended } from '@nuxt/test-utils/runtime'
import Button from '~/components/ui/Button.vue'

test('Button renders correctly', async () => {
  const component = await mountSuspended(Button, {
    props: { label: 'Click me' }
  })
  expect(component.text()).toContain('Click me')
})

import { mockNuxtImport } from '@nuxt/test-utils/runtime'

// Mock 自动导入的 composable
mockNuxtImport('useFetch', () => {
  return () => ({
    data: ref({ items: [] }),
    pending: ref(false),
    error: ref(null)
  })
})

import { $fetch, setup } from '@nuxt/test-utils/e2e'

await setup({ server: true })

test('GET /api/products', async () => {
  const data = await $fetch('/api/products')
  expect(data).toHaveProperty('items')
})

import { expect, test } from '@playwright/test'
import { setup, $fetch } from '@nuxt/test-utils/e2e'

await setup({ server: true })

test('home page renders', async ({ page }) => {
  await page.goto('/')
  await expect(page.locator('h1')).toHaveText('Welcome')
})

// composables/useAuth.ts
export const useAuth = () => {
  const user = useState('user', () => null)
  const fetch = useRequestFetch()  // 自动转发 SSR Cookie

  const { data } = await useAsyncData('user', () =>
    fetch('/api/auth/me').catch(() => null)
  )
  user.value = data.value

  return { user, isLoggedIn: computed(() => !!user.value) }
}

// 抛出错误
throw createError({
  statusCode: 404,
  statusMessage: 'Page Not Found',
  fatal: true
})

// 全局错误处理插件
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('app:error', (error) => {
    console.error('Global error:', error)
  })
})

                              ┌──────────────────┐
                              │   浏览器/客户端    │
                              └────────┬─────────┘
                                       │
                          HTTP 请求（首次请求 / API 调用）
                                       │
                              ┌────────▼─────────┐
                              │   Nitro Server    │
                              │   (h3 路由匹配)   │
                              └───┬──────────┬───┘
                                  │          │
                     ┌────────────▼──┐  ┌────▼────────────┐
                     │  SSR 渲染路径  │  │  API 路由路径    │
                     │               │  │                  │
                     │ 创建 Vue App  │  │ 执行 Handler    │
                     │ 执行 setup()  │  │ defineEventHandler│
                     │ useFetch →    │  │                  │
                     │ 直接调用      │  │ 返回 JSON       │
                     │ API Handler   │  │                  │
                     │ (无网络开销)  │  └────────┬────────┘
                     │               │          │
                     │ 渲染 HTML     │          │
                     │ 序列化 payload │          │
                     └───────┬───────┘          │
                             │                  │
                    HTML + Payload           JSON 响应
                             │                  │
                      ┌──────▼──────────────────▼──┐
                      │        浏览器接收            │
                      └──────┬──────────────────┬──┘
                             │                  │
                     渲染 HTML（立即可见）        │
                     下载 JS Bundle              │
                             │                  │
                      ┌──────▼──────┐           │
                      │   水合阶段   │           │
                      │ 读取 payload │           │
                      │ 恢复状态    │           │
                      │ 绑定事件    │           │
                      │ 激活响应式  │           │
                      └──────┬──────┘           │
                             │                  │
                      ┌──────▼──────┐           │
                      │  可交互状态  │           │
                      │ 后续导航:    │           │
                      │ 客户端路由   │           │
                      │ + API 请求  │───────────┘
                      └─────────────┘

// server/plugins/customRenderer.ts
export default defineStritroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    // html 结构：
    // {
    //   htmlAttrs: string[],      // <html> 的属性
    //   head: string[],           // <head> 内容
    //   bodyAttrs: string[],      // <body> 的属性
    //   bodyPrepend: string[],    // <body> 开头注入
    //   body: string[],           // <body> 主要内容
    //   bodyAppend: string[]      // <body> 结尾注入
    // }

    html.head.push('<meta name="custom" content="value" />')
    html.bodyAppend.push('<script>console.log("injected")</script>')
  })
})

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'custom-preset',
    rollupConfig: {
      // 自定义 Rollup 配置
    }
  }
})

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    './base-app',              // 本地路径
    'my-shared-layer',         // npm 包
    'github:org/repo'          // GitHub 仓库
  ]
})

// 在代码中可以使用 # 前缀引用虚拟文件
import { useAppConfig } from '#app'
import { useRuntimeConfig } from '#imports'