Nuxt.js模块系统 #

一、模块概述 #

Nuxt.js 模块是扩展 Nuxt 核心功能的方式。模块可以在构建时修改 Nuxt 配置、添加插件、注册组件等。

1.1 模块的作用 #

添加新功能
集成第三方服务
修改构建配置
添加插件和中间件
注册组件和组合式函数

1.2 内置模块 #

@nuxtjs/tailwindcss：Tailwind CSS 集成
@nuxtjs/i18n：国际化支持
@nuxtjs/supabase：Supabase 集成
@nuxtjs/apollo：GraphQL 客户端

二、使用模块 #

2.1 安装模块 #

bash

pnpm add @nuxtjs/tailwindcss

2.2 配置模块 #

nuxt.config.ts：

typescript

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',
    '@nuxtjs/i18n'
  ]
})

2.3 模块配置 #

typescript

export default defineNuxtConfig({
  modules: [
    ['@nuxtjs/tailwindcss', {
      cssPath: '~/assets/css/tailwind.css',
      configPath: 'tailwind.config.js'
    }]
  ]
})

2.4 条件加载 #

typescript

export default defineNuxtConfig({
  modules: process.env.NODE_ENV === 'development' 
    ? ['@nuxtjs/devtools']
    : []
})

三、创建本地模块 #

3.1 简单模块 #

modules/my-module.ts：

typescript

import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    
    addPlugin(resolve('./runtime/plugin'))
  }
})

3.2 带配置的模块 #

modules/analytics.ts：

typescript

import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'

interface ModuleOptions {
  trackingId: string
  enabled: boolean
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'analytics',
    configKey: 'analytics'
  },
  
  defaults: {
    trackingId: '',
    enabled: true
  },
  
  setup(options, nuxt) {
    if (!options.enabled) return
    
    const { resolve } = createResolver(import.meta.url)
    
    nuxt.options.runtimeConfig.public.analytics = {
      trackingId: options.trackingId
    }
    
    addPlugin(resolve('./runtime/plugin'))
  }
})

使用：

nuxt.config.ts：

typescript

export default defineNuxtConfig({
  modules: ['./modules/analytics'],
  
  analytics: {
    trackingId: 'UA-XXXXX-Y',
    enabled: true
  }
})

3.3 模块插件 #

modules/analytics/runtime/plugin.ts：

typescript

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  
  if (import.meta.client && config.public.analytics?.trackingId) {
    window.dataLayer = window.dataLayer || []
    
    function gtag(...args: any[]) {
      window.dataLayer.push(args)
    }
    
    gtag('js', new Date())
    gtag('config', config.public.analytics.trackingId)
    
    return {
      provide: {
        gtag
      }
    }
  }
})

四、模块API #

4.1 定义模块 #

typescript

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'module-name',
    configKey: 'moduleName',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  
  defaults: {},
  
  async setup(options, nuxt) {
    
  }
})

4.2 Kit工具函数 #

函数	说明
`addPlugin`	添加插件
`addImports`	添加自动导入
`addComponentsDir`	添加组件目录
`addServerHandler`	添加服务端路由
`addBuildPlugin`	添加构建插件
`extendPages`	扩展页面
`extendViteConfig`	扩展 Vite 配置

4.3 添加自动导入 #

typescript

import { defineNuxtModule, addImports } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    addImports([
      {
        name: 'useMyFeature',
        from: resolve('./runtime/composables/useMyFeature')
      }
    ])
  }
})

4.4 添加组件 #

typescript

import { defineNuxtModule, addComponentsDir } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    addComponentsDir({
      path: resolve('./runtime/components'),
      prefix: 'My'
    })
  }
})

4.5 添加服务端路由 #

typescript

import { defineNuxtModule, addServerHandler } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    addServerHandler({
      route: '/api/my-module/data',
      handler: resolve('./runtime/server/api/data')
    })
  }
})

五、完整模块示例 #

5.1 模块结构 #

text

modules/
└── my-analytics/
    ├── index.ts
    ├── runtime/
    │   ├── plugin.ts
    │   ├── composables/
    │   │   └── useAnalytics.ts
    │   └── components/
    │       └── Analytics.vue
    └── types.ts

5.2 模块入口 #

modules/my-analytics/index.ts：

typescript

import { defineNuxtModule, addPlugin, addImports, addComponentsDir, createResolver } from '@nuxt/kit'

interface AnalyticsOptions {
  trackingId: string
  enabled?: boolean
  debug?: boolean
}

export default defineNuxtModule<AnalyticsOptions>({
  meta: {
    name: 'my-analytics',
    configKey: 'analytics',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  
  defaults: {
    enabled: true,
    debug: false
  },
  
  async setup(options, nuxt) {
    if (!options.enabled) return
    
    const { resolve } = createResolver(import.meta.url)
    
    nuxt.options.runtimeConfig.public.analytics = {
      trackingId: options.trackingId,
      debug: options.debug
    }
    
    addPlugin(resolve('./runtime/plugin'))
    
    addImports([
      {
        name: 'useAnalytics',
        from: resolve('./runtime/composables/useAnalytics')
      }
    ])
    
    addComponentsDir({
      path: resolve('./runtime/components'),
      prefix: 'Analytics'
    })
    
    if (options.debug) {
      console.log('[Analytics Module] Initialized with tracking ID:', options.trackingId)
    }
  }
})

5.3 模块插件 #

modules/my-analytics/runtime/plugin.ts：

typescript

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()
  
  if (!import.meta.client || !config.public.analytics?.trackingId) return
  
  const script = document.createElement('script')
  script.async = true
  script.src = `https://www.googletagmanager.com/gtag/js?id=${config.public.analytics.trackingId}`
  document.head.appendChild(script)
  
  window.dataLayer = window.dataLayer || []
  
  function gtag(...args: any[]) {
    window.dataLayer.push(args)
  }
  
  gtag('js', new Date())
  gtag('config', config.public.analytics.trackingId)
  
  return {
    provide: {
      gtag,
      trackEvent: (event: string, params?: Record<string, any>) => {
        gtag('event', event, params)
      }
    }
  }
})

5.4 组合式函数 #

modules/my-analytics/runtime/composables/useAnalytics.ts：

typescript

export const useAnalytics = () => {
  const { $gtag, $trackEvent } = useNuxtApp()
  
  const trackPageView = (path: string) => {
    $gtag('config', useRuntimeConfig().public.analytics.trackingId, {
      page_path: path
    })
  }
  
  const trackEvent = (event: string, params?: Record<string, any>) => {
    $trackEvent(event, params)
  }
  
  return {
    trackPageView,
    trackEvent
  }
}

5.5 使用模块 #

nuxt.config.ts：

typescript

export default defineNuxtConfig({
  modules: ['./modules/my-analytics'],
  
  analytics: {
    trackingId: 'G-XXXXXXXXXX',
    enabled: true,
    debug: process.env.NODE_ENV === 'development'
  }
})

六、发布模块 #

6.1 package.json #

json

{
  "name": "nuxt-my-module",
  "version": "1.0.0",
  "main": "./dist/module.mjs",
  "types": "./dist/types.d.ts",
  "exports": {
    ".": {
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs",
      "types": "./dist/types.d.ts"
    }
  },
  "files": [
    "dist"
  ],
  "peerDependencies": {
    "nuxt": "^3.0.0"
  },
  "keywords": [
    "nuxt",
    "nuxt3",
    "nuxt-module"
  ]
}

6.2 构建配置 #

typescript

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['./src/module'],
  clean: true,
  declaration: true,
  externals: ['nuxt', '@nuxt/kit']
})

七、最佳实践 #

7.1 模块命名 #

使用 nuxt- 前缀
使用 kebab-case
描述性名称

7.2 配置设计 #

typescript

interface ModuleOptions {
  enabled?: boolean
  apiKey?: string
  features?: {
    featureA?: boolean
    featureB?: boolean
  }
}

7.3 类型安全 #

typescript

declare module '@nuxt/schema' {
  interface NuxtConfig {
    myModule?: ModuleOptions
  }
  interface RuntimeConfig {
    public: {
      myModule: {
        apiKey: string
      }
    }
  }
}

八、总结 #

本章介绍了 Nuxt.js 模块系统：

使用和配置模块
创建本地模块
模块 API 和 Kit 工具函数
完整模块示例
发布模块

模块系统是扩展 Nuxt.js 功能的强大方式，下一章我们将学习服务端渲染。