模块作者指南

学习如何创建 Nuxt 模块，以集成、增强或扩展任何 Nuxt 应用。

Nuxt 的配置和钩子系统使得定制 Nuxt 的各个方面并添加任何你可能需要的集成（Vue 插件、CMS、服务器路由、组件、日志等）成为可能。

Nuxt 模块 是在使用 nuxt dev 启动开发模式或使用 nuxt build 构建生产项目时依次运行的函数。
通过模块，你可以封装、规范测试并作为 npm 包分享自定义解决方案，而无需给项目添加不必要的样板代码，或修改 Nuxt 本身。

快速开始

我们推荐你使用我们的模块起始模板开始你的 Nuxt 模块开发：

npm create nuxt -- -t module my-module

yarn create nuxt -t module my-module

pnpm create nuxt -t module my-module

bun create nuxt -- -t module my-module

这将创建一个名为 my-module 的项目，带有开发和发布模块所需的所有样板代码。

下一步：

在你喜欢的 IDE 中打开 my-module
使用你喜欢的包管理器安装依赖
使用 npm run dev:prepare 准备本地开发文件
按照本文档了解更多关于 Nuxt 模块的内容

使用起始模板

了解如何使用模块起始模板执行基础任务。

观看 Vue School 关于 Nuxt 模块起始模板的视频。

如何开发

虽然你的模块源代码位于 src 目录内，但大多数场景中，开发模块时你需要一个 Nuxt 应用。这就是 playground 目录的用途。它是一个已配置好可以搭配你的模块一起运行的 Nuxt 应用，方便你调试。

你可以像使用任何 Nuxt 应用一样使用 playground。

通过 npm run dev 启动开发服务器，当你更改 src 目录下的模块时，服务器会自动重载
通过 npm run dev:build 构建 playground

所有其他 nuxt 命令都可以针对 playground 目录使用（例如 nuxt <COMMAND> playground）。你也可以在 package.json 中自定义其他 dev:* 脚本来调用它们，方便使用。

如何测试

模块起始模板附带了基础的测试套件：

使用 ESLint 进行代码检查，命令：npm run lint
使用 Vitest 进行测试运行，命令：npm run test 或 npm run test:watch

你可以根据需要扩展默认的测试策略以适应你的需求。

如何构建

Nuxt 模块自带由 @nuxt/module-builder 提供的构建工具。该构建器无需你配置，支持 TypeScript，确保你的资源能够正确打包并分发至其他 Nuxt 应用。

你可以运行 npm run prepack 来构建你的模块。

虽然某些情况下构建模块很有用，但大多数时候你不需要自己构建：开发时 playground 会帮你处理，发布时也有发布脚本协助。

如何发布

在发布模块到 npm 之前，确保你有一个 npmjs.com 账户，并已通过 npm login 在本地登录认证。

你可以通过提升版本号后使用 npm publish 命令发布，但模块起始模板带有一个发布脚本，可以帮助你确保发布一个可用的模块版本到 npm 以及更多操作。

使用发布脚本前，先提交所有更改（建议遵循 Conventional Commits，以利用自动版本升级和变更日志更新），然后运行 npm run release。

发布脚本运行时会：

先执行测试套件：
- 运行代码检查（npm run lint）
- 运行单元测试、集成测试和端到端测试（npm run test）
- 构建模块（npm run prepack）
如果测试一切正常，继续发布模块：
- 根据 Conventional Commits 自动提升版本号并生成变更日志
- 发布模块到 npm（此过程中，模块会再构建一次，确保版本号生效）
- 将表示新版本的 git 标签推送到远程仓库

和其他脚本一样，你可以根据需要在 package.json 中调整默认的 release 脚本。

模块开发

Nuxt 模块提供了多种强大的 API 和模式，允许它们以各种方式改变 Nuxt 应用。本节教你如何利用它们。

模块结构

我们可以区分两种 Nuxt 模块：

已发布的模块，通过 npm 发布 —— 你可以在 Nuxt 官方网站查看部分社区模块列表。
“本地”模块，存在于 Nuxt 项目内，可能内嵌在 Nuxt 配置中或作为 modules 目录的一部分。

无论哪种，结构都很相似。

模块定义

使用起始模板时，你的模块定义位于 src/module.ts。

模块定义是你的模块入口。Nuxt 在配置中引用模块时会加载它。

底层而言，Nuxt 模块定义是一个简单（可能是异步）的函数，接收内联选项和一个 nuxt 对象，用于与 Nuxt 交互。

export default function (inlineOptions, nuxt) {
  // 你可以自由操作...
  console.log(inlineOptions.token) // `123`
  console.log(nuxt.options.dev) // `true` 或 `false`
  nuxt.hook('ready', async nuxt => {
    console.log('Nuxt 已准备好')
  })
}

你可以使用 Nuxt Kit 提供的更高级的 defineNuxtModule 辅助函数，获得类型提示支持。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook('pages:extend', pages => {
    console.log(`发现了 ${pages.length} 个页面`)
  })
})

但我们不推荐使用底层的函数定义。定义模块时，推荐使用带有 meta 属性的对象语法，尤其是要发布到 npm 时。

该辅助函数通过实现大量模块常用模式，使定义 Nuxt 模块更简单，保证未来兼容性，提升模块作者和用户体验。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    // 通常是你的模块在 npm 的包名
    name: '@nuxtjs/example',
    // `nuxt.config` 中持有模块选项的字段名
    configKey: 'sample',
    // 兼容性约束
    compatibility: {
      // 支持的 nuxt 版本范围，遵循 Semver 规范
      nuxt: '>=3.0.0'
    }
  },
  // 模块的默认配置选项，也可以是返回选项的函数
  defaults: {},
  // 简捷注册 Nuxt 钩子
  hooks: {},
  // 其他模块依赖配置——这并不保证依赖模块先于你的模块运行
  // 但允许你在依赖模块运行前修改其配置
  moduleDependencies: {
    'some-module': {
      // 依赖模块的版本约束。如果版本不符，Nuxt 启动时会报错。
      version: '>=2',
      // 默认情况下，除非 optional 被设置，否则会安装列出的依赖模块。
      optional: true,
      // 用于覆盖 `nuxt.options` 中的配置
      overrides: {},
      // 用于设置的默认配置，会覆盖依赖模块默认值，但不会覆盖用户 `nuxt.options` 配置
      defaults: {}
    }
  },
  // 模块逻辑主体，支持异步
  setup(moduleOptions, nuxt) {
    // ...
  }
})

最终，defineNuxtModule 返回一个带有低级 (inlineOptions, nuxt) 签名的包装函数。此函数会处理默认配置等步骤后调用你的 setup：

支持 defaults 与 meta.configKey 自动合并模块选项
类型提示和自动类型推断
提供基本 Nuxt 2 兼容的垫片
确保模块只安装一次，使用 meta.name 或 meta.configKey 生成唯一键
自动注册 Nuxt 钩子
自动检查兼容性问题（基于模块元信息）
为 Nuxt 内部使用暴露 getOptions 和 getMeta
确保只要使用最新 @nuxt/kit 的 defineNuxtModule，模块保持向后和向前兼容
集成模块构建工具链

运行时目录

使用起始模板时，运行时目录位于 src/runtime。

模块和 Nuxt 配置中的其它内容不会包含在应用运行时，但你可能希望模块提供运行时代码或注入代码到应用中，这就是运行时目录的作用。

在运行时目录内，你可以提供与 Nuxt 应用相关的任意资源：

Vue 组件
组合式函数（composables）
Nuxt 插件

对服务器引擎 Nitro 提供：

API 路由
中间件
Nitro 插件

或者任何你想注入用户 Nuxt 应用的资源：

样式表
3D 模型
图片
等等

然后，你可以从你的模块定义中注入这些资源。

了解更多关于资源注入内容，请参阅示例章节。

已发布的模块不能利用运行时目录内资源的自动导入机制。它们必须从 #imports 等位置显式导入。
原因是性能考虑，自动导入不会应用到位于 node_modules（即已发布模块所在）内的文件。

工具链

模块配备了一套官方工具，帮助你进行开发。

`@nuxt/module-builder`

Nuxt 模块构建器是零配置构建工具，承担了构建和打包模块的繁重工作，确保模块构建产物与 Nuxt 应用的兼容。

`@nuxt/kit`

Nuxt Kit 提供组合式实用工具，帮助模块与 Nuxt 应用交互。推荐尽可能使用 Nuxt Kit 而非手动替代方案，以保证更好的兼容性和代码可读性。

Read more in Docs > Guide > Going Further > Kit.

`@nuxt/test-utils`

Nuxt 测试工具包含一系列实用工具，帮助你在模块测试中设置和运行 Nuxt 应用。

示例

这里展示了编写模块时使用的常见模式。

修改 Nuxt 配置

模块可以读取并修改 Nuxt 配置。示例如下，启用一个实验性功能：

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // 如果尚未存在，创建 `experimental` 对象
    nuxt.options.experimental ||= {}
    nuxt.options.experimental.componentIslands = true
  }
})

当需要处理更复杂的配置修改时，建议使用 defu。

观看 Vue School 关于修改 Nuxt 配置的视频。

将选项暴露到运行时

因为模块不属于应用运行时，它们的选项也不会自动包含在内。但在许多情况下，你可能需要在运行时代码中访问某些模块选项。推荐使用 Nuxt 的 runtimeConfig 来暴露需要的配置。

import { defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(nuxt.options.runtimeConfig.public.myModule, {
      foo: options.foo
    })
  }
})

注意此处使用 defu 来扩展用户提供的公共运行时配置，而非覆盖。

然后你可以在插件、组件或应用中像使用其他运行时配置一样访问模块选项：

const options = useRuntimeConfig().public.myModule

请谨慎避免在公共运行时配置中暴露敏感配置信息，如私有 API 密钥，因为它们会被打包进公共代码。

Read more in Docs > Guide > Going Further > Runtime Config.

观看 Vue School 关于传递和暴露 Nuxt 模块选项的视频。

使用 `addPlugin` 注入插件

插件是模块添加运行时逻辑的常用方式。你可以用 addPlugin 辅助来注册插件。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // 创建解析器处理相对路径
    const resolver = createResolver(import.meta.url)

    addPlugin(resolver.resolve('./runtime/plugin'))
  }
})

Read more in Docs > Guide > Going Further > Kit.

使用 `addComponent` 注入 Vue 组件

如果模块需要提供 Vue 组件，你可以用 addComponent 将它们注册为 Nuxt 的自动导入组件。

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // 从运行时目录导入组件
    addComponent({
      name: 'MySuperComponent', // 组件在 Vue 模板中的名称
      export: 'MySuperComponent', // （可选）如果是具名导出
      filePath: resolver.resolve('runtime/components/MySuperComponent.vue')
    })

    // 从第三方库导入组件
    addComponent({
      name: 'MyAwesomeComponent', 
      export: 'MyAwesomeComponent', 
      filePath: '@vue/awesome-components'
    })
  }
})

或者，你可以使用 addComponentsDir 一次性添加整个目录：

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addComponentsDir({
      path: resolver.resolve('runtime/components')
    })
  }
})

使用 `addImports` 和 `addImportsDir` 注入组合式函数（composables）

如果模块需要提供组合式函数，可以用 addImports 来添加自动导入。

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImports({
      name: 'useComposable', // 组合函数名称
      as: 'useComposable',
      from: resolver.resolve('runtime/composables/useComposable') // 组合函数路径
    })
  }
})

也可使用 addImportsDir 添加整个目录：

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImportsDir(resolver.resolve('runtime/composables'))
  }
})

使用 `addServerHandler` 注入服务器路由

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/hello',
      handler: resolver.resolve('./runtime/server/api/hello/index.get')
    })
  }
})

还可以添加动态服务器路由：

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

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/hello/:name',
      handler: resolver.resolve('./runtime/server/api/hello/[name].get')
    })
  }
})

注入其他类型资源

如果模块需要注入其它资源，也可以如此进行。示例如下，模块通过 Nuxt 的 css 数组注入样式表：

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

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.options.css.push(resolver.resolve('./runtime/style.css'))
  }
})

一个更高级的示例，模块通过 Nitro 的 publicAssets 选项暴露一整目录资源：

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

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('nitro:config', async (nitroConfig) => {
      nitroConfig.publicAssets ||= []
      nitroConfig.publicAssets.push({
        dir: resolver.resolve('./runtime/public'),
        maxAge: 60 * 60 * 24 * 365 // 一年
      })
    })
  }
})

在你的模块中使用其它模块

模块如需依赖其他模块，可使用 Nuxt Kit 的 installModule 功能。举例，如果你想在模块中使用 Nuxt Tailwind：

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

export default defineNuxtModule<ModuleOptions>({
  async setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // 注入包含 Tailwind 指令的 CSS 文件
    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))

    await installModule('@nuxtjs/tailwindcss', {
      // 模块配置
      exposeConfig: true,
      config: {
        darkMode: 'class',
        content: {
          files: [
            resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
            resolver.resolve('./runtime/*.{mjs,js,ts}')
          ]
        }
      }
    })
  }
})

使用钩子

生命周期钩子允许你扩展 Nuxt 的几乎所有方面。模块可通过定义钩子映射或编程调用方式注册。

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

export default defineNuxtModule({
  // 通过 hooks 映射注册 `app:error` 钩子
  hooks: {
    'app:error': (err) => {
      console.info(`捕获错误：${err}`);
    }
  },
  setup (options, nuxt) {
    // 编程方式注册 `pages:extend` 钩子
    nuxt.hook('pages:extend', (pages) => {
      console.info(`发现了 ${pages.length} 个页面`);
    })
  }
})

Read more in Docs > API > Advanced > Hooks.

观看 Vue School 关于在模块中使用 Nuxt 生命周期钩子的视频。

模块清理
如果你的模块开启、处理或启动监听器，应该在 Nuxt 生命周期结束时关闭它们。可以使用 close 钩子。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async nuxt => {
      // 你的自定义清理代码
    })
  }
})

自定义钩子

模块也能定义并调用自己的钩子，这是一种强大模式，可以让你的模块更具扩展性。

如果你期望其它模块订阅你的钩子，应在 modules:done 钩子中调用它们，确保所有模块均已完成设置并注册监听。

// my-module/module.ts
import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleHooks {
  'my-module:custom-hook': (payload: { foo: string }) => void
}

export default defineNuxtModule({
  setup (options, nuxt) {
    // 在 modules:done 中调用钩子
    nuxt.hook('modules:done', async () => {
      const payload = { foo: 'bar' }
      await nuxt.callHook('my-module:custom-hook', payload)
    })
  }
})

添加模板/虚拟文件

如果你需要添加虚拟文件，供用户项目中导入，可用 addTemplate 工具。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // 文件会加入 Nuxt 内部虚拟文件系统，可通过 '#build/my-module-feature.mjs' 导入
    addTemplate({
      filename: 'my-module-feature.mjs',
      getContents: () => 'export const myModuleFeature = () => "hello world !"'
    })
  }
})

服务端应使用 addServerTemplate。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // 文件加入 Nitro 虚拟文件系统，可在服务器代码中通过 'my-server-module.mjs' 导入
    addServerTemplate({
      filename: 'my-server-module.mjs',
      getContents: () => 'export const myServerModule = () => "hello world !"'
    })
  }
})

添加类型声明

你可能想给用户项目添加类型声明（比如扩展 Nuxt 接口或定义全局类型）。Nuxt 提供了 addTypeTemplate 辅助，写入模板到磁盘并在生成的 nuxt.d.ts 中添加引用。

如果模块需扩展 Nuxt 管理的类型，可用 addTypeTemplate 实现：

import { defineNuxtModule, addTemplate, addTypeTemplate } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `// 由 my-module 生成
        interface MyModuleNitroRules {
          myModule?: { foo: 'bar' }
        }
        declare module 'nitropack/types' {
          interface NitroRouteRules extends MyModuleNitroRules {}
          interface NitroRouteConfig extends MyModuleNitroRules {}
        }
        export {}`
    })
  }
})

若需更细粒度控制，可使用 prepare:types 钩子，注册回调注入类型：

const template = addTemplate({ /* 模板选项 */ })
nuxt.hook('prepare:types', ({ references }) => {
  references.push({ path: template.dst })
})

更新模板

如果需要更新模板/虚拟文件，可以用 updateTemplates：

nuxt.hook('builder:watch', async (event, path) => {
  if (path.includes('my-module-feature.config')) {
    // 重新加载已注册的模板
    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
  }
})

测试

测试帮助保证模块在各种配置下的预期工作。以下内容讲述如何对模块做各种测试。

单元测试及集成测试

我们仍在讨论和探索如何简化 Nuxt 模块的单元及集成测试。

查看此 RFC 参与讨论。

端到端测试

Nuxt 测试工具是帮助模块进行端到端测试的首选库。流程如下：

在 test/fixtures/* 内创建用于测试的 Nuxt 应用“夹具”（fixture）
在测试文件中使用夹具搭建 Nuxt
用 @nuxt/test-utils 提供的工具与夹具交互（如请求页面）
对夹具执行断言（如“HTML 包含…”）
重复上述过程

示例夹具：

test/fixtures/ssr/nuxt.config.ts

// 1. 创建用于测试的 Nuxt 应用
import MyModule from '../../../src/module'

export default defineNuxtConfig({
  ssr: true,
  modules: [
    MyModule
  ]
})

及对应测试：

test/rendering.ts

import { describe, it, expect } from 'vitest'
import { fileURLToPath } from 'node:url'
import { setup, $fetch } from '@nuxt/test-utils/e2e'

describe('ssr', async () => {
  // 2. 在测试文件中搭建 Nuxt 应用
  await setup({
    rootDir: fileURLToPath(new URL('./fixtures/ssr', import.meta.url)),
  })

  it('渲染首页', async () => {
    // 3. 调用测试工具与夹具交互
    const html = await $fetch('/')

    // 4. 断言结果
    expect(html).toContain('<div>ssr</div>')
  })
})

// 5. 可继续添加更多测试用例
describe('csr', async () => { /* ... */ })

此流程的示例可见于模块起始模板。

如果模块设置时间超过 1 秒，Nuxt 会发出警告。

公开接口应添加前缀

模块应对任何公开的配置、插件、API、组合函数或组件添加明显前缀，避免与其它模块或内部冲突。

理想做法是用模块名作为前缀（例如模块名为 nuxt-foo，则导出 <FooButton> 组件与 useFooBar() 而非 <Button> 和 useBar()）。

使用生命周期钩子做一次性初始化

模块若需执行一次性初始化（例如生成配置文件、设置数据库、安装依赖等），应使用生命周期钩子，而非放在主 setup 函数。

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

export default defineNuxtModule({
  meta: {
    name: 'my-database-module',
    version: '1.0.0',
  },
  async onInstall (nuxt) {
    // 一次性初始化：创建数据库模式、生成配置文件等
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (options, nuxt, previousVersion) {
    // 版本迁移
    if (semver.lt(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // 常规构建逻辑，每次构建执行
    addServerHandler({ /* ... */ })
  },
})

该模式避免每次构建重复工作，提升开发体验。详见生命周期钩子文档。

为什么使用此模块？
如何使用此模块？
模块具体功能是什么？

同时链接至集成网站和文档会更好。

第三方及其他社区模块 通常前缀为 nuxt-，任何人均可发布。使用此前缀方便在 npm 上被搜索到，是尝试新想法的好起点！

私有或个人模块 是为自己或公司定制的模块，无需遵循任何命名规则，通常在 npm 组织范围内（如 @my-company/nuxt-auth）。

列出你的社区模块

任何社区模块均欢迎在模块列表中被收录。申请收录请在 nuxt/modules 仓库中开 Issue。Nuxt 团队将协助你应用最佳实践。

加入 `nuxt-modules` 和 `@nuxtjs/`

将模块迁移到 nuxt-modules 意味着随时有人协助，也能联合力量打造完美解决方案。

如果你已有发布且正常工作的模块，想将其转入 nuxt-modules，请在 nuxt/modules 提交 Issue。

加入 nuxt-modules 后，我们可将你的社区模块重命名为 @nuxtjs/ 范围包，并为其文档提供子域（例如 my-module.nuxtjs.org）。

Was this helpful?

报告问题或者在 GitHub 上编辑此页面

生命周期钩子

Nuxt 提供了一个强大的钩子系统，可以扩展几乎所有方面。

Nuxt Kit

@nuxt/kit 提供模块作者所需的功能。