Nuxt 模块系统与插件开发

// 模块定义的基本结构
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  // 模块元数据
  meta: {
    name: 'my-awesome-module',
    configKey: 'myModule',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  
  // 默认配置选项
  defaults: {
    enabled: true,
    apiEndpoint: '/api/data'
  },
  
  // 模块核心逻辑
  setup(options, nuxt) {
    // 模块初始化逻辑
    console.log('Module initialized with options:', options)
    
    // 访问 Nuxt 实例进行扩展
    nuxt.hook('ready', () => {
      console.log('Nuxt application is ready!')
    })
  }
})

// 示例：API 缓存模块
export default defineNuxtModule({
  meta: {
    name: 'nuxt-api-cache',
    configKey: 'apiCache'
  },
  defaults: {
    ttl: 3600,
    storage: 'memory'
  },
  setup(options, nuxt) {
    // 添加服务端中间件
    addServerHandler({
      route: '/api/**',
      handler: createCacheHandler(options)
    })
    
    // 注册缓存清理任务
    nuxt.hook('close', () => {
      clearCache()
    })
  }
})

// 示例：UI 组件库模块
export default defineNuxtModule({
  meta: {
    name: 'nuxt-ui-components',
    configKey: 'uiComponents'
  },
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    
    // 自动注册组件
    addComponentsDir({
      path: resolve('./runtime/components'),
      prefix: 'Ui',
      global: true
    })
    
    // 添加样式文件
    addTemplate({
      filename: 'ui-components.css',
      src: resolve('./runtime/styles/main.css')
    })
    
    // 注入全局样式
    nuxt.options.css.push('#build/ui-components.css')
  }
})

// 示例：第三方服务集成模块
export default defineNuxtModule({
  meta: {
    name: 'nuxt-analytics',
    configKey: 'analytics'
  },
  defaults: {
    trackingId: '',
    enableInDev: false
  },
  setup(options, nuxt) {
    // 验证必要配置
    if (!options.trackingId) {
      throw new Error('Analytics tracking ID is required')
    }
    
    // 只在生产环境或开发环境允许时加载
    if (nuxt.options.dev && !options.enableInDev) {
      return
    }
    
    // 添加客户端插件
    addPlugin({
      src: resolve('./runtime/plugin.client.ts'),
      mode: 'client'
    })
    
    // 注入配置到运行时
    nuxt.options.runtimeConfig.public.analytics = {
      trackingId: options.trackingId
    }
  }
})

// nuxt.config.ts - 图像优化模块配置
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  
  image: {
    // 多提供商配置
    providers: {
      cloudinary: {
        baseURL: 'https://res.cloudinary.com/demo/image/fetch/'
      },
      imgix: {
        baseURL: 'https://assets.imgix.net/'
      }
    },
    
    // 预设配置
    presets: {
      avatar: {
        modifiers: {
          format: 'webp',
          width: 50,
          height: 50,
          quality: 80
        }
      },
      cover: {
        modifiers: {
          format: 'webp',
          width: 800,
          height: 600,
          fit: 'cover'
        }
      }
    },
    
    // 全局配置
    screens: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      xxl: 1536
    },
    
    // 域名配置
    domains: ['example.com', 'images.unsplash.com']
  }
})

/**
 * Nuxt 图像模块核心架构定义
 * 
 * 采用分层架构设计，实现图像处理能力的模块化扩展和运行时优化
 */
interface ModuleArchitecture {
  /** 
   * 提供者抽象层 - 负责不同图像服务提供商的适配工作
   * @property abstract - 图像提供者抽象接口定义
   * @property implementations - 具体提供商实现（示例包含 Cloudinary/Imgix/Static 三种类型）
   */
  providerLayer: {
    abstract: ImageProvider
    implementations: CloudinaryProvider | ImgixProvider | StaticProvider
  }

  /**
   * 运行时处理层 - 负责客户端图像转换和优化逻辑
   * @property imageTransformation - 图像转换核心功能
   * @property optimizationEngine - 智能优化引擎
   */
  runtimeLayer: {
    imageTransformation: {
      urlGenerator: (options: ImageOptions) => string // 根据配置生成优化后的图片URL
      srcsetGenerator: (breakpoints: number[]) => string // 生成响应式图片的srcset属性
    }
    optimizationEngine: {
      formatConversion: 'webp' | 'avif' // 自动格式转换策略（优先现代图片格式）
      qualityPresets: Map<string, number> // 质量预设配置（如：{ 'thumbnail': 80, 'high': 95 }）
    }
  }

  /**
   * Nitro 服务集成层 - 服务端图像处理相关功能
   * @property devMiddleware - 开发环境中间件（用于实时图像处理）
   * @property productionHandler - 生产环境请求处理器（对接CDN或存储服务）
   * @property cacheStorage - 缓存存储策略（文件系统存储或内存存储）
   */
  nitroIntegration: {
    devMiddleware: ImageMiddleware
    productionHandler: ImageEndpoint
    cacheStorage: FSStorage | MemoryStorage
  }
}

/**
 * @nuxt/image 核心实现流程：
 * 
 * 1. 模块初始化阶段：
 * - 读取nuxt.config中的图像配置
 * - 注册图像提供者（Cloudinary/Imgix等）
 * - 注入运行时组件和工具方法
 */
export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'nuxt-image',
    configKey: 'image'
  },
  setup(options, nuxt) {
    // 注册图像提供者
    const provider = createImageProvider(options.provider)
    
    // 注入运行时工具
    nuxt.hook('imports:extend', (imports) => {
      imports.push({ name: 'useImage', as: 'useImage', from: '#image' })
    })
  }
})

/**
 * 2. 运行时处理流程：
 * - 解析组件属性（<NuxtImg> / <NuxtPicture>）
 * - 根据设备特性生成优化参数
 * - 构建提供者特定的图片URL
 */
function createImageURL(src: string, modifiers: ImageModifiers) {
  // 1. 应用全局默认配置
  const mergedModifiers = { ...defaults, ...modifiers }
  
  // 2. 设备适配处理
  applyDeviceAdaptation(mergedModifiers)
  
  // 3. 生成提供者特定URL
  return provider.generateURL(src, mergedModifiers)
}

/**
 * 3. 服务端集成流程：
 * - 开发模式下注册图片优化中间件
 * - 生产环境配置CDN路由规则
 * - 缓存策略管理
 */
nuxt.hook('nitro:config', (nitroConfig) => {
  if (process.env.NODE_ENV === 'development') {
    nitroConfig.handlers.push({
      route: '/_image/development/**',
      handler: '#image/devHandler'
    })
  }
})

/**
 * 4. 构建优化阶段：
 * - 图片资源扫描与预处理
 * - 生成响应式图片的srcset
 * - 生成现代图片格式的fallback
 */
nuxt.hook('build:before', () => {
  analyzeImages().then((assets) => {
    generateResponsiveVariants(assets)
    generateFormatFallbacks()
  })
})

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  
  pinia: {
    storesDirs: ['./stores/**', './custom-folder/stores/**'],
    autoImports: ['defineStore', 'acceptHMRUpdate']
  }
})

// 示例：用户认证状态管理
// stores/auth.ts
import { defineStore } from 'pinia'

export const useAuthStore = defineStore('auth', {
  state: () => ({
    user: null as User | null,
    token: '',
    expiresAt: 0
  }),
  
  actions: {
    async login(credentials: LoginPayload) {
      const { data } = await useFetch('/api/auth/login', {
        method: 'POST',
        body: credentials
      })
      
      if (data.value) {
        this.user = data.value.user
        this.token = data.value.token
        this.expiresAt = data.value.expiresAt
      }
    },
    
    logout() {
      this.$reset()
      useCookie('auth_token').value = null
    }
  },
  
  getters: {
    isAuthenticated: (state) => state.expiresAt > Date.now()
  }
})

// 组件中使用
const auth = useAuthStore()

/**
 * @pinia/nuxt 模块核心架构：
 * 
 * 1. 模块注册阶段：
 * - 自动注册 Pinia 到 Nuxt 应用
 * - 配置 Vue 插件和 SSR 支持
 * - 设置自动导入目录 (stores/*)
 */
export default defineNuxtModule({
  meta: {
    name: 'pinia',
    configKey: 'pinia'
  },
  
  setup(options, nuxt) {
    // 添加 Pinia 类型定义
    nuxt.hook('prepare:types', ({ references }) => {
      references.push({ types: 'pinia' })
    })
    
    // 注册 Pinia Vue 插件
    nuxt.hook('modules:done', () => {
      addVuePlugin(Pinia.createPinia())
    })
    
    // 配置自动导入
    extendPages((pages) => {
      pages.push({
        name: 'stores',
        path: resolve(nuxt.options.srcDir, 'stores'),
        prefix: 'use',
        pattern: '**/*.ts'
      })
    })
    
    // SSR 状态序列化处理
    nuxt.hook('app:rendered', ({ ssrContext }) => {
      if (ssrContext) {
        ssrContext.payload.pinia = pinia.state.value
      }
    })
  }
})

// 服务端状态序列化
nuxt.hook('vue:setup', () => {
  if (process.server) {
    const pinia = usePinia()
    nuxt.payload.pinia = pinia.state.value
  }
})

// 客户端状态水合
if (process.client && nuxt.payload.pinia) {
  const pinia = usePinia()
  pinia.state.value = nuxt.payload.pinia
}

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
  
  tailwindcss: {
    cssPath: '~/assets/css/tailwind.css',
    configPath: 'tailwind.config.js',
    exposeConfig: true,
    viewer: true,
    // 仅在开发环境启用 JIT
    jit: true
  }
})

// tailwind.config.js - 企业级配置
module.exports = {
  content: [
    './components/**/*.{js,vue,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './plugins/**/*.{js,ts}',
    './app.vue'
  ],
  
  theme: {
    extend: {
      // 自定义颜色系统
      colors: {
        primary: {
          50: '#f0f9ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        gray: {
          50: '#f9fafb',
          900: '#111827',
        }
      },
      
      // 自定义字体
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace']
      },
      
      // 自定义间距
      spacing: {
        '18': '4.5rem',
        '88': '22rem'
      },
      
      // 自定义动画
      animation: {
        'fade-in': 'fadeIn 0.5s ease-in-out',
        'slide-up': 'slideUp 0.3s ease-out'
      },
      
      keyframes: {
        fadeIn: {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' }
        },
        slideUp: {
          '0%': { transform: 'translateY(100%)' },
          '100%': { transform: 'translateY(0)' }
        }
      }
    },
  },
  
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/aspect-ratio')
  ]
}

// utils/module-compatibility.ts
interface ModuleCompatibility {
  nuxtVersion: string
  nodeVersion: string
  dependencies: Record<string, string>
  conflicts: string[]
}

export const checkModuleCompatibility = (
  moduleName: string, 
  moduleVersion: string
): Promise<ModuleCompatibility> => {
  return new Promise(async (resolve, reject) => {
    try {
      // 检查模块元数据
      const modulePackage = await import(`${moduleName}/package.json`)
      const compatibility = modulePackage.nuxt || {}
      
      // 验证 Nuxt 版本兼容性
      const nuxtVersion = process.env.NUXT_VERSION || '3.0.0'
      if (!semver.satisfies(nuxtVersion, compatibility.nuxt || '*')) {
        throw new Error(`Module ${moduleName} is not compatible with Nuxt ${nuxtVersion}`)
      }
      
      resolve({
        nuxtVersion: compatibility.nuxt,
        nodeVersion: compatibility.node || '>= 16.0.0',
        dependencies: modulePackage.peerDependencies || {},
        conflicts: compatibility.conflicts || []
      })
    } catch (error) {
      reject(error)
    }
  })
}

// plugins/secure-module-loader.ts
export default defineNuxtPlugin(async () => {
  const config = useRuntimeConfig()
  
  // 安全模块加载器
  const loadSecureModule = async (moduleName: string, options: any = {}) => {
    try {
      // 验证模块来源
      if (!config.app.trustedModules.includes(moduleName)) {
        console.warn(`Module ${moduleName} is not in trusted list`)
        return null
      }
      
      // 动态导入模块
      const module = await import(moduleName)
      
      // 沙盒环境初始化
      const sandboxOptions = {
        ...options,
        sandbox: true,
        permissions: config.app.modulePermissions[moduleName] || {}
      }
      
      return module.default(sandboxOptions)
    } catch (error) {
      console.error(`Failed to load module ${moduleName}:`, error)
      return null
    }
  }
  
  return {
    provide: {
      loadSecureModule
    }
  }
})

// composables/useModuleConfig.ts
export const useModuleConfig = <T = any>(moduleName: string) => {
  const nuxtApp = useNuxtApp()
  const runtimeConfig = useRuntimeConfig()
  
  // 获取模块配置
  const getConfig = (): T => {
    const appConfig = nuxtApp.$config[moduleName]
    const runtimeModuleConfig = runtimeConfig[moduleName]
    const envConfig = process.env[`NUXT_${moduleName.toUpperCase()}`]
    
    // 配置优先级: 环境变量 > 运行时配置 > 应用配置
    return {
      ...appConfig,
      ...runtimeModuleConfig,
      ...(envConfig ? JSON.parse(envConfig) : {})
    } as T
  }
  
  // 监听配置变化
  const configRef = ref<T>(getConfig())
  
  const updateConfig = (newConfig: Partial<T>) => {
    configRef.value = { ...configRef.value, ...newConfig }
    
    // 触发模块重新初始化
    nuxtApp.hooks.callHook('module:config:updated', moduleName, configRef.value)
  }
  
  return {
    config: readonly(configRef),
    updateConfig,
    refresh: () => { configRef.value = getConfig() }
  }
}

my-nuxt-module/
├── src/
│   ├── module.ts              # 模块入口文件
│   └── runtime/
│       ├── components/        # 运行时组件
│       ├── composables/       # 组合式函数
│       ├── plugins/           # 运行时插件
│       ├── server/            # 服务端代码
│       └── types.ts           # TypeScript 类型定义
├── playground/                # 开发测试环境
├── docs/                      # 文档
├── build.config.ts            # 构建配置
├── package.json
└── README.md

// src/module.ts - 完整的模块开发示例
import { 
  defineNuxtModule, 
  createResolver, 
  addPlugin,
  addServerHandler,
  addComponentsDir,
  addImports,
  addTemplate,
  installModule
} from '@nuxt/kit'
import { defu } from 'defu'

export interface ModuleOptions {
  enabled: boolean
  apiKey: string
  endpoint: string
  enableLogging: boolean
  cacheStrategy: 'memory' | 'redis' | 'filesystem'
  rateLimit: {
    enabled: boolean
    requests: number
    window: number
  }
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'nuxt-advanced-api',
    configKey: 'advancedApi',
    compatibility: {
      nuxt: '^3.0.0',
      bridge: false
    }
  },
  
  defaults: {
    enabled: true,
    apiKey: '',
    endpoint: '/api',
    enableLogging: false,
    cacheStrategy: 'memory',
    rateLimit: {
      enabled: false,
      requests: 100,
      window: 3600
    }
  },
  
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    
    // 1. 验证配置
    if (!options.apiKey && nuxt.options.dev) {
      console.warn('API key is not provided for advanced-api module')
    }
    
    // 2. 条件性模块初始化
    if (!options.enabled) {
      console.info('Advanced API module is disabled')
      return
    }
    
    // 3. 安装依赖模块
    installModule('@pinia/nuxt')
    
    // 4. 注册运行时插件
    addPlugin({
      src: resolve('./runtime/plugins/api-client.ts'),
      mode: 'all'
    })
    
    addPlugin({
      src: resolve('./runtime/plugins/error-handler.client.ts'),
      mode: 'client'
    })
    
    // 5. 添加服务端处理器
    addServerHandler({
      route: `${options.endpoint}/**`,
      handler: resolve('./runtime/server/api-proxy.ts')
    })
    
    // 6. 注册组件
    addComponentsDir({
      path: resolve('./runtime/components'),
      prefix: 'Api',
      global: true
    })
    
    // 7. 添加组合式函数
    addImports([
      {
        name: 'useApiClient',
        as: 'useApiClient',
        from: resolve('./runtime/composables/useApiClient')
      },
      {
        name: 'useApiCache',
        as: 'useApiCache', 
        from: resolve('./runtime/composables/useApiCache')
      }
    ])
    
    // 8. 生成配置文件模板
    addTemplate({
      filename: 'advanced-api.config.mjs',
      getContents: () => `
        export default ${JSON.stringify(options, null, 2)}
      `
    })
    
    // 9. 注入运行时配置
    nuxt.options.runtimeConfig.advancedApi = defu(
      nuxt.options.runtimeConfig.advancedApi as any,
      {
        apiKey: options.apiKey,
        endpoint: options.endpoint,
        enableLogging: options.enableLogging
      }
    )
    
    nuxt.options.runtimeConfig.public.advancedApi = defu(
      nuxt.options.runtimeConfig.public.advancedApi as any,
      {
        endpoint: options.endpoint,
        cacheStrategy: options.cacheStrategy
      }
    )
    
    // 10. 注册生命周期钩子
    nuxt.hook('nitro:config', (nitroConfig) => {
      // 配置 Nitro 存储
      nitroConfig.storage = nitroConfig.storage || {}
      nitroConfig.storage.apiCache = {
        driver: options.cacheStrategy === 'redis' ? 'redis' : 'fs',
        base: './data/api-cache'
      }
    })
    
    nuxt.hook('build:done', () => {
      console.info('Advanced API module build completed')
    })
    
    // 11. 开发环境增强
    if (nuxt.options.dev) {
      // 添加开发工具
      addPlugin({
        src: resolve('./runtime/plugins/dev-tools.client.ts'),
        mode: 'client'
      })
    }
  }
})

// 导出类型定义供 TypeScript 使用
declare module '@nuxt/schema' {
  interface NuxtConfig {
    advancedApi?: Partial<ModuleOptions>
  }
  interface NuxtOptions {
    advancedApi?: ModuleOptions
  }
}

declare module 'nuxt/schema' {
  interface NuxtConfig {
    advancedApi?: Partial<ModuleOptions>
  }
  interface NuxtOptions {
    advancedApi?: ModuleOptions
  }
}

// src/runtime/composables/useApiClient.ts
export const useApiClient = () => {
  const config = useRuntimeConfig()
  const { $apiCache } = useNuxtApp()
  
  const apiClient = $fetch.create({
    baseURL: config.public.advancedApi.endpoint,
    headers: {
      'Authorization': `Bearer ${config.advancedApi.apiKey}`
    },
    
    onRequest({ request, options }) {
      if (config.advancedApi.enableLogging) {
        console.log('API Request:', request, options)
      }
    },
    
    onResponse({ response }) {
      if (config.advancedApi.enableLogging) {
        console.log('API Response:', response.status, response._data)
      }
    },
    
    onResponseError({ response }) {
      console.error('API Error:', response.status, response._data)
      throw createError({
        statusCode: response.status,
        statusMessage: response._data?.message || 'API request failed'
      })
    }
  })
  
  const cachedFetch = async <T>(url: string, options: any = {}): Promise<T> => {
    const cacheKey = `api:${url}:${JSON.stringify(options)}`
    
    // 尝试从缓存获取
    const cached = await $apiCache.get<T>(cacheKey)
    if (cached) {
      return cached
    }
    
    // 执行请求
    const result = await apiClient<T>(url, options)
    
    // 存储到缓存
    await $apiCache.set(cacheKey, result, options.ttl || 300)
    
    return result
  }
  
  return {
    client: apiClient,
    cachedFetch,
    clearCache: () => $apiCache.clear()
  }
}

// src/runtime/server/api-proxy.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  const method = getMethod(event)
  const path = getRouterParam(event, '_')
  
  // 速率限制检查
  if (config.advancedApi.rateLimit.enabled) {
    const clientIP = getClientIP(event)
    const isAllowed = await checkRateLimit(clientIP, config.advancedApi.rateLimit)
    
    if (!isAllowed) {
      throw createError({
        statusCode: 429,
        statusMessage: 'Too many requests'
      })
    }
  }
  
  try {
    // 代理请求到外部 API
    const response = await $fetch(`${config.advancedApi.remoteEndpoint}/${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${config.advancedApi.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: method !== 'GET' ? await readBody(event) : undefined
    })
    
    return response
  } catch (error) {
    throw createError({
      statusCode: error.statusCode || 500,
      statusMessage: error.message || 'Proxy request failed'
    })
  }
})

async function checkRateLimit(
  clientIP: string, 
  config: { requests: number; window: number }
): Promise<boolean> {
  const storage = useStorage('apiCache')
  const key = `ratelimit:${clientIP}`
  const now = Date.now()
  
  const requests = await storage.getItem<number[]>(key) || []
  const validRequests = requests.filter(time => now - time < config.window * 1000)
  
  if (validRequests.length >= config.requests) {
    return false
  }
  
  validRequests.push(now)
  await storage.setItem(key, validRequests, { ttl: config.window })
  
  return true
}

// 完整的生命周期钩子示例
export default defineNuxtModule({
  setup(options, nuxt) {
    // 1. 模块配置阶段
    nuxt.hook('modules:before', () => {
      console.log('Before modules initialization')
    })
    
    nuxt.hook('modules:done', () => {
      console.log('All modules loaded')
    })
    
    // 2. 配置解析阶段
    nuxt.hook('ready', () => {
      console.log('Nuxt is ready, configuration is resolved')
    })
    
    // 3. 构建准备阶段
    nuxt.hook('build:before', () => {
      console.log('Before build starts')
      // 在此阶段可以修改构建配置
    })
    
    // 4. Nitro 配置阶段
    nuxt.hook('nitro:config', (nitroConfig) => {
      console.log('Configuring Nitro server')
      // 配置服务端功能
      nitroConfig.plugins = nitroConfig.plugins || []
      nitroConfig.plugins.push(resolve('./runtime/server/nitro-plugin.ts'))
    })
    
    // 5. Vite/Webpack 配置阶段
    nuxt.hook('vite:extendConfig', (config) => {
      console.log('Extending Vite configuration')
      // 扩展构建工具配置
      config.plugins = config.plugins || []
      config.plugins.push(customVitePlugin())
    })
    
    // 6. 构建完成阶段
    nuxt.hook('build:done', () => {
      console.log('Build completed')
      // 执行构建后任务
    })
    
    // 7. 生成阶段 (仅 SSG)
    nuxt.hook('generate:before', () => {
      console.log('Before static generation')
    })
    
    nuxt.hook('generate:done', () => {
      console.log('Static generation completed')
    })
    
    // 8. 应用关闭阶段
    nuxt.hook('close', async () => {
      console.log('Cleaning up module resources')
      // 清理资源
      await cleanupResources()
    })
  }
})

// src/runtime/plugins/lifecycle-manager.ts
export default defineNuxtPlugin({
  name: 'lifecycle-manager',
  parallel: false,
  setup(nuxtApp) {
    // 应用创建阶段
    nuxtApp.hook('app:created', (vueApp) => {
      console.log('Vue app created')
      
      // 注册全局属性
      vueApp.config.globalProperties.$moduleUtils = createModuleUtils()
      
      // 设置错误处理
      vueApp.config.errorHandler = (error, instance, info) => {
        console.error('Global error:', error, info)
        // 发送错误报告
        sendErrorReport(error, instance, info)
      }
    })
    
    // 应用挂载前
    nuxtApp.hook('app:beforeMount', () => {
      console.log('Before Vue app mount')
      // 初始化全局状态
      initializeGlobalState()
    })
    
    // 应用挂载后
    nuxtApp.hook('app:mounted', () => {
      console.log('Vue app mounted')
      // 启动后台任务
      startBackgroundTasks()
    })
    
    // 页面导航钩子
    nuxtApp.hook('page:start', () => {
      console.log('Page navigation started')
      // 显示加载指示器
      showLoadingIndicator()
    })
    
    nuxtApp.hook('page:finish', () => {
      console.log('Page navigation finished')
      // 隐藏加载指示器
      hideLoadingIndicator()
    })
    
    // 错误处理钩子
    nuxtApp.hook('vue:error', (error, instance, info) => {
      console.error('Vue error:', error, info)
      // 优雅的错误处理
      handleVueError(error, instance, info)
    })
    
    return {
      provide: {
        moduleLifecycle: {
          onReady: (callback: Function) => {
            nuxtApp.hook('app:mounted', callback)
          },
          onError: (callback: Function) => {
            nuxtApp.hook('vue:error', callback)
          }
        }
      }
    }
  }
})

{
  "name": "@yourorg/nuxt-advanced-api",
  "version": "1.0.0",
  "description": "Advanced API module for Nuxt 3",
  "keywords": ["nuxt", "api", "cache", "rate-limit"],
  "homepage": "https://github.com/yourorg/nuxt-advanced-api",
  "bugs": {
    "url": "https://github.com/yourorg/nuxt-advanced-api/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/nuxt-advanced-api.git"
  },
  "license": "MIT",
  "author": {
    "name": "Your Name",
    "email": "your.email@example.com"
  },
  "main": "./dist/module.mjs",
  "types": "./dist/types.d.ts",
  "exports": {
    ".": {
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs"
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "nuxt-module-build",
    "dev": "nuxi dev playground",
    "dev:build": "nuxi build playground",
    "dev:prepare": "nuxt-module-build --stub && nuxi prepare playground",
    "docs:dev": "nuxi dev docs",
    "docs:build": "nuxi generate docs",
    "lint": "eslint .",
    "test": "vitest",
    "test:coverage": "vitest --coverage",
    "prepack": "nuxt-module-build"
  },
  "dependencies": {
    "@nuxt/kit": "^3.0.0",
    "defu": "^6.1.0"
  },
  "devDependencies": {
    "@nuxt/module-builder": "^0.5.0",
    "@nuxt/test-utils": "^3.0.0",
    "@types/node": "^18.0.0",
    "nuxt": "^3.0.0",
    "vitest": "^0.34.0"
  },
  "peerDependencies": {
    "nuxt": "^3.0.0"
  },
  "nuxt": {
    "compatibility": {
      "nuxt": "^3.0.0"
    }
  }
}

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm run test:coverage
      
      - name: Build module
        run: npm run build
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3

  release:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build module
        run: npm run build
      
      - name: Generate changelog
        run: npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
      
      - name: Publish to NPM
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      
      - name: Create GitHub Release
        uses: actions/create-release@v1
        with:
          tag_name: ${{ github.ref_name }}
          release_name: Release ${{ github.ref_name }}
          body_path: CHANGELOG.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

// docs/nuxt.config.ts - 文档站点配置
export default defineNuxtConfig({
  extends: ['@nuxt/content-theme-docs'],
  
  content: {
    highlight: {
      theme: 'github-dark'
    }
  },
  
  app: {
    head: {
      title: 'Nuxt Advanced API Module',
      meta: [
        { name: 'description', content: 'Advanced API module documentation' }
      ]
    }
  }
})

<!-- docs/content/1.introduction.md -->
# Introduction

The Nuxt Advanced API module provides a comprehensive solution for API management in Nuxt applications.

## Features

- 🚀 High-performance API proxy
- 💾 Intelligent caching strategies
- 🛡️ Built-in rate limiting
- 📊 Request/response logging
- 🔒 Security enhancements
- 📈 Performance monitoring

## Quick Start

```bash
npm install @yourorg/nuxt-advanced-api

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@yourorg/nuxt-advanced-api'],
  
  advancedApi: {
    apiKey: process.env.API_KEY,
    endpoint: '/api',
    cacheStrategy: 'redis'
  }
})

<script setup>
const { cachedFetch } = useApiClient()

const { data } = await cachedFetch('/users', {
  ttl: 300 // 5 minutes cache
})
</script>

## 7.3 插件系统深度开发

### 7.3.1 插件的创建与注册

#### 插件基础架构

```typescript
// plugins/advanced-features.ts - 高级插件开发模式
export default defineNuxtPlugin({
  name: 'advanced-features',
  
  // 插件依赖关系
  dependsOn: ['pinia', 'vue-router'],
  
  // 并行执行控制
  parallel: true,
  
  // 环境控制
  mode: 'all', // 'client' | 'server' | 'all'
  
  async setup(nuxtApp) {
    // 1. 初始化核心服务
    const logger = createLogger('advanced-features')
    const eventBus = createEventBus()
    const storage = createStorage()
    
    // 2. 注册全局属性
    nuxtApp.provide('logger', logger)
    nuxtApp.provide('eventBus', eventBus)
    nuxtApp.provide('storage', storage)
    
    // 3. 设置全局错误处理
    nuxtApp.hook('vue:error', (error, instance, info) => {
      logger.error('Vue Error:', { error, instance, info })
      
      // 发送错误报告
      if (process.client) {
        sendErrorToService(error, instance, info)
      }
    })
    
    // 4. 路由拦截器
    if (process.client) {
      const router = useRouter()
      
      router.beforeEach(async (to, from) => {
        logger.info(`Navigation: ${from.path} -> ${to.path}`)
        
        // 权限检查
        if (to.meta.requiresAuth && !isAuthenticated()) {
          throw createError({
            statusCode: 401,
            statusMessage: 'Authentication required'
          })
        }
        
        // 页面分析
        trackPageView(to.path)
      })
    }
    
    return {
      provide: {
        // 导出可在应用中使用的方法
        utils: {
          formatDate: (date: Date) => date.toISOString(),
          generateId: () => Math.random().toString(36).substring(7)
        }
      }
    }
  }
})

// plugins/server-enhancement.server.ts
export default defineNuxtPlugin({
  name: 'server-enhancement',
  
  async setup(nuxtApp) {
    const config = useRuntimeConfig()
    
    // 1. 服务端日志系统
    const serverLogger = {
      request: (req: any) => {
        console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`)
      },
      
      error: (error: Error, context: any) => {
        console.error(`[ERROR] ${error.message}`, {
          stack: error.stack,
          context,
          timestamp: new Date().toISOString()
        })
      },
      
      performance: (operation: string, duration: number) => {
        console.log(`[PERF] ${operation}: ${duration}ms`)
      }
    }
    
    // 2. 响应增强
    nuxtApp.hook('render:html', (html, { event }) => {
      const duration = Date.now() - event.context.requestStart
      serverLogger.performance('SSR Render', duration)
      
      // 添加性能头
      setHeader(event, 'X-Render-Time', `${duration}ms`)
      setHeader(event, 'X-Server-Instance', process.env.INSTANCE_ID || 'unknown')
    })
    
    return {
      provide: {
        serverLogger
      }
    }
  }
})

// plugins/client-enhancement.client.ts
export default defineNuxtPlugin({
  name: 'client-enhancement',
  
  async setup(nuxtApp) {
    // 1. 客户端存储管理
    const clientStorage = {
      set: (key: string, value: any, expiry?: number) => {
        const item = {
          value,
          expiry: expiry ? Date.now() + expiry : null
        }
        localStorage.setItem(key, JSON.stringify(item))
      },
      
      get: (key: string) => {
        const item = localStorage.getItem(key)
        if (!item) return null
        
        try {
          const parsed = JSON.parse(item)
          if (parsed.expiry && Date.now() > parsed.expiry) {
            localStorage.removeItem(key)
            return null
          }
          return parsed.value
        } catch {
          return null
        }
      },
      
      remove: (key: string) => localStorage.removeItem(key),
      clear: () => localStorage.clear()
    }
    
    // 2. 设备信息检测
    const deviceInfo = reactive({
      userAgent: navigator.userAgent,
      platform: navigator.platform,
      language: navigator.language,
      cookieEnabled: navigator.cookieEnabled,
      onLine: navigator.onLine,
      screenWidth: window.screen.width,
      screenHeight: window.screen.height,
      viewportWidth: window.innerWidth,
      viewportHeight: window.innerHeight,
      isMobile: /Mobi|Android/i.test(navigator.userAgent),
      isTablet: /iPad|Tablet/i.test(navigator.userAgent),
      isDesktop: !/Mobi|Android|iPad|Tablet/i.test(navigator.userAgent)
    })
    
    return {
      provide: {
        clientStorage,
        deviceInfo: readonly(deviceInfo)
      }
    }
  }
})

// plugins/01.foundation.ts
export default defineNuxtPlugin({
  name: 'foundation',
  parallel: false, // 串行执行，确保基础服务先初始化
  
  setup(nuxtApp) {
    // 基础服务初始化
    const logger = createLogger()
    const eventBus = createEventBus()
    const httpClient = createHttpClient()
    
    nuxtApp.provide('logger', logger)
    nuxtApp.provide('eventBus', eventBus)
    nuxtApp.provide('httpClient', httpClient)
    
    return {
      provide: {
        foundation: {
          logger,
          eventBus,
          httpClient
        }
      }
    }
  }
})

// plugins/02.authentication.ts
export default defineNuxtPlugin({
  name: 'authentication',
  dependsOn: ['foundation'], // 依赖基础插件
  parallel: false,
  
  async setup(nuxtApp) {
    const { $logger, $httpClient } = nuxtApp
    
    const authService = {
      currentUser: ref(null),
      
      async login(credentials: any) {
        try {
          const response = await $httpClient.post('/api/auth/login', credentials)
          this.currentUser.value = response.user
          return response
        } catch (error) {
          $logger.error('Login failed:', error)
          throw error
        }
      },
      
      async logout() {
        await $httpClient.post('/api/auth/logout')
        this.currentUser.value = null
      }
    }
    
    return {
      provide: {
        auth: authService
      }
    }
  }
})