Nuxt 模块开发与发布完整指南

为什么要开发 Nuxt 模块

当你发现某个功能在多个项目中重复使用，或者想要封装复杂的配置，模块化是最佳选择。

模块初始化

使用官方脚手架创建模块：

npx nuxi init my-module -t module
cd my-module
npm install

项目结构

my-module/
├── src/
│   ├── module.ts        # 模块入口
│   ├── runtime/         # 运行时代码
│   │   ├── plugin.ts    # 插件
│   │   └── composables/ # 组合式函数
│   └── types.ts         # 类型定义
├── playground/          # 测试应用
├── test/                # 测试文件
└── package.json

模块开发

基本模块结构

// src/module.ts
import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'

export interface ModuleOptions {
  apiKey?: string
  debug?: boolean
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    debug: false
  },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)
    
    // 添加插件
    addPlugin(resolver.resolve('./runtime/plugin'))
    
    // 添加组合式函数自动导入
    addImports({
      name: 'useMyFeature',
      from: resolver.resolve('./runtime/composables/useMyFeature')
    })
    
    // 将选项暴露给运行时
    nuxt.options.runtimeConfig.public.myModule = options
  }
})

关键说明： 使用 @nuxt/kit 提供的工具函数可以安全地扩展 Nuxt 功能，确保与 Nuxt 版本的兼容性。

运行时插件

// src/runtime/plugin.ts
import { defineNuxtPlugin, useRuntimeConfig } from '#app'

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  const options = config.public.myModule
  
  return {
    provide: {
      myFeature: {
        doSomething() {
          if (options.debug) {
            console.log('Doing something...')
          }
        }
      }
    }
  }
})

组合式函数

// src/runtime/composables/useMyFeature.ts
import { ref, computed } from 'vue'
import { useRuntimeConfig } from '#app'

export function useMyFeature() {
  const config = useRuntimeConfig()
  const count = ref(0)
  
  const increment = () => count.value++
  const isDebug = computed(() => config.public.myModule.debug)
  
  return { count, increment, isDebug }
}

测试模块

使用 Playground

npm run dev:prepare
npm run dev

编写测试

// test/module.test.ts
import { describe, it, expect } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils'

describe('my-module', async () => {
  await setup({
    rootDir: fileURLToPath(new URL('./fixtures/basic', import.meta.url))
  })
  
  it('renders the module output', async () => {
    const html = await $fetch('/')
    expect(html).toContain('My Module Works')
  })
})

发布到 npm

准备发布

// package.json
{
  "name": "nuxt-my-module",
  "version": "1.0.0",
  "main": "./dist/module.cjs",
  "module": "./dist/module.mjs",
  "types": "./dist/types.d.ts",
  "files": ["dist"],
  "keywords": ["nuxt", "nuxt-module"]
}

构建与发布

npm run build
npm publish

最佳实践

1. 类型安全：完整的 TypeScript 支持
2. 文档完善：README 包含使用示例
3. 版本规范：遵循语义化版本
4. 测试覆盖：确保核心功能有测试
5. 更新日志：维护 CHANGELOG

开发 Nuxt 模块是参与社区、提升技术影响力的好方式。