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

Nuxt 模块是在使用 nuxt dev 启动 Nuxt 开发模式或使用 nuxt build 构建生产项目时顺序运行的函数。通过模块，您可以将自定义解决方案封装、正确测试并作为 npm 包共享，而无需向项目添加不必要的样板代码或要求更改 Nuxt 本身。

快速开始

我们建议您使用我们的入门模板开始使用 Nuxt 模块：

npm create nuxt -- -t module my-module

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

接下来的步骤：

1. 在您选择的 IDE 中打开 my-module
2. 使用您喜欢的包管理器安装依赖项
3. 使用 npm run dev:prepare 准备本地文件进行开发
4. 按照本文档了解有关 Nuxt 模块的更多信息

使用入门模板

了解如何使用模块入门模板执行基本任务。

如何开发

虽然您的模块源代码位于 src 目录中，但在大多数情况下，要开发一个模块，您需要一个 Nuxt 应用程序。这就是 playground 目录的作用。它是一个 Nuxt 应用程序，您可以随意修改，已经配置为与您的模块一起运行。

您可以像与任何 Nuxt 应用程序一样与 playground 交互。

• 使用 npm run dev 启动其开发服务器，当您在 src 目录中对模块进行更改时，它应该会自动重新加载
• 使用 npm run dev:build 构建它

如何测试

模块入门模板附带一个基本的测试套件：

• 由 ESLint 提供支持的 linter，使用 npm run lint 运行
• 由 Vitest 提供支持的测试运行器，使用 npm run test 或 npm run test:watch 运行

如何构建

Nuxt 模块附带由 @nuxt/module-builder 提供的构建器。此构建器不需要您进行任何配置，支持 TypeScript，并确保您的资产被正确打包以分发给其他 Nuxt 应用程序。

您可以通过运行 npm run prepack 来构建您的模块。

如何发布

虽然您可以通过提升版本并使用 npm publish 命令来发布模块，但模块入门模板附带一个发布脚本，可以帮助您确保将模块的工作版本发布到 npm 以及更多。

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

运行发布脚本时，将发生以下情况：

• 首先，它将运行您的测试套件：
  • 运行 linter (npm run lint)
  • 运行单元、集成和 e2e 测试 (npm run test)
  • 构建模块 (npm run prepack)
• 然后，如果您的测试套件运行良好，它将继续发布您的模块：
  • 根据您的 Conventional Commits 提升模块版本并生成变更日志
  • 将模块发布到 npm（为此目的，模块将再次构建，以确保其更新的版本号在发布的工件中被考虑）
  • 将代表新发布版本的 git 标签推送到您的 git 远程源

开发模块

Nuxt 模块附带各种强大的 API 和模式，允许它们以几乎任何可能的方式更改 Nuxt 应用程序。本节将教您如何利用这些功能。

模块结构

我们可以考虑两种类型的 Nuxt 模块：

• 已发布的模块在 npm 上分发 - 您可以在 Nuxt 网站 上查看一些社区模块的列表。
• “本地”模块，它们存在于 Nuxt 项目本身中，或者内联在 Nuxt 配置中，或者作为模块目录的一部分。

无论哪种情况，它们的结构都是相似的。

模块定义

模块定义是模块的入口点。当您的模块在 Nuxt 配置中被引用时，它会被 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: {},
  // 持有模块逻辑的函数，可以是异步的
  setup(moduleOptions, nuxt) {
    // ...
  }
})

最终，defineNuxtModule 返回一个带有低级 (inlineOptions, nuxt) 模块签名的包装函数。此包装函数在调用您的 setup 函数之前应用默认值和其他必要步骤：

• 支持 defaults 和 meta.configKey 以自动合并模块选项
• 类型提示和自动类型推断
• 为基本的 Nuxt 2 兼容性添加 shims
• 使用从 meta.name 或 meta.configKey 计算的唯一键确保模块仅安装一次
• 自动注册 Nuxt 钩子
• 根据模块元数据自动检查兼容性问题
• 为 Nuxt 的内部使用公开 getOptions 和 getMeta
• 确保模块使用最新版本的 @nuxt/kit 的 defineNuxtModule 时的向后和向上兼容性
• 与模块构建工具集成

运行时目录

模块与 Nuxt 配置中的所有内容一样，不包含在应用程序运行时中。然而，您可能希望模块提供或注入运行时代码到其安装的应用程序中。这就是运行时目录使您能够做到的。

在运行时目录中，您可以提供与 Nuxt 应用相关的任何类型的资产：

• Vue 组件
• 可组合的
• Nuxt 插件

对于 服务器引擎，Nitro：

• API 路由
• 中间件
• Nitro 插件

或者您希望注入到用户的 Nuxt 应用中的任何其他类型的资产：

• 样式表
• 3D 模型
• 图片
• 等等

然后，您将能够从模块定义中将所有这些资产注入到应用程序中。

工具

模块附带一组第一方工具，以帮助您进行开发。

@nuxt/module-builder

Nuxt 模块构建器 是一个零配置的构建工具，负责构建和发布模块的所有繁重工作。它确保模块构建工件与 Nuxt 应用程序的正确兼容性。

@nuxt/kit

Nuxt Kit 提供可组合的实用程序，以帮助模块与 Nuxt 应用程序交互。建议尽可能使用 Nuxt Kit 实用程序而不是手动替代方案，以确保模块的更好兼容性和代码可读性。

@nuxt/test-utils

Nuxt Test Utils 是一组实用程序，帮助在模块测试中设置和运行 Nuxt 应用程序。

配方

在这里找到用于编写模块的常见模式。

更改 Nuxt 配置

模块可以读取和更改 Nuxt 配置。以下是一个启用实验性功能的模块示例。

import { defineNuxtModule } from '@nuxt/kit'

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

当您需要处理更复杂的配置更改时，您应该考虑使用 defu。

向运行时公开选项

因为模块不是应用程序运行时的一部分，所以它们的选项也不是。然而，在许多情况下，您可能需要在运行时代码中访问某些模块选项。我们建议使用 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

使用 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'))
  }
})

使用 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', // 在 vue 模板中使用的组件名称
      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 注入可组合的

如果模块应提供可组合的，您可以使用 addImports 实用程序将它们添加为自动导入，以便 Nuxt 解析。

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 // 1 年
      })
    })
  }
})

在模块中使用其他模块

如果模块依赖于其他模块，您可以使用 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 的几乎每个方面。模块可以通过编程方式或通过其定义中的 hooks 映射来挂钩它们。

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} 个页面`);
    })
  }
})

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async nuxt => {
      // 您的自定义代码在这里
    })
  }
})

添加模板/虚拟文件

如果您需要添加一个可以导入到用户应用程序中的虚拟文件，可以使用 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' {
          interface NitroRouteRules extends MyModuleNitroRules {}
          interface NitroRouteConfig extends MyModuleNitroRules {}
        }
        export {}`
    })
  }
})

如果您需要更细粒度的控制，可以使用 prepare:types 钩子注册一个回调，以注入您的类型。

const template = addTemplate({ /* template options */ })
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 Test Utils 是帮助您以端到端方式测试模块的首选库。以下是使用它的工作流程：

1. 创建一个 Nuxt 应用程序作为 "fixture" 使用，位于 test/fixtures/*
2. 在测试文件中使用此 fixture 设置 Nuxt
3. 使用 @nuxt/test-utils 的实用程序与 fixture 交互（例如，获取页面）
4. 执行与此 fixture 相关的检查（例如，“HTML 包含 ...”）
5. 重复

实际上，fixture：

// 1. 创建一个 Nuxt 应用程序作为 "fixture" 使用
import MyModule from '../../../src/module'

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

及其测试：

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

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

  it('渲染索引页面', async () => {
    // 3. 使用 `@nuxt/test-utils` 的实用程序与 fixture 交互
    const html = await $fetch('/')

    // 4. 执行与此 fixture 相关的检查
    expect(html).toContain('<div>ssr</div>')
  })
})

// 5. 重复
describe('csr', async () => { /* ... */ })

使用 Playground 和外部进行手动 QA

在开发模块时拥有一个用于测试模块的 playground Nuxt 应用程序非常有用。模块入门模板为此集成了一个。

您可以在本地使用其他 Nuxt 应用程序（不属于模块存储库的应用程序）测试模块。为此，您可以使用 npm pack 命令或您的包管理器等效命令，从模块创建一个 tarball。然后在测试项目中，您可以将模块添加到 package.json 包中，如："my-module": "file:/path/to/tarball.tgz"。

之后，您应该能够像在任何常规项目中一样引用 my-module。

最佳实践

强大的功能伴随着巨大的责任。虽然模块功能强大，但在编写模块时请记住以下最佳实践，以保持应用程序的性能和开发者体验。

异步模块

如我们所见，Nuxt 模块可以是异步的。例如，您可能希望开发一个需要获取某些 API 或调用异步函数的模块。

然而，请小心异步行为，因为 Nuxt 将等待模块设置完成后再进入下一个模块并启动开发服务器、构建过程等。最好将耗时的逻辑推迟到 Nuxt 钩子中。

始终为公开的接口添加前缀

Nuxt 模块应为任何公开的配置、插件、API、可组合的或组件提供明确的前缀，以避免与其他模块和内部冲突。

理想情况下，您应该使用模块的名称作为前缀（例如，如果模块名为 nuxt-foo，则公开 <FooButton> 和 useFooBar()，而不是 <Button> 和 useBar()）。

友好的 TypeScript

Nuxt 拥有一流的 TypeScript 集成，以提供最佳的开发者体验。

即使用户不直接使用 TypeScript，公开类型并使用 TypeScript 开发模块也会使用户受益。

避免 CommonJS 语法

Nuxt 依赖于原生 ESM。请阅读原生 ES 模块以获取更多信息。

文档化模块使用

考虑在 readme 文件中记录模块使用：

• 为什么使用此模块？
• 如何使用此模块？
• 此模块做什么？

链接到集成网站和文档总是一个好主意。

提供 StackBlitz 演示或样板

提供一个包含模块的最小重现和 StackBlitz 是一个好习惯，您可以将其添加到模块的 readme 中。

这不仅为模块的潜在用户提供了一个快速简便的方式来试验模块，还为他们提供了一个简单的方法来构建最小的重现，以便在遇到问题时发送给您。

不要宣传特定的 Nuxt 版本

Nuxt、Nuxt Kit 和其他新工具旨在同时考虑向前和向后兼容性。

请使用“X for Nuxt”而不是“X for Nuxt 3”以避免生态系统中的碎片化，并优先使用 meta.compatibility 设置 Nuxt 版本约束。

遵循入门模板的默认设置

模块入门模板附带一组默认的工具和配置（例如 ESLint 配置）。如果您计划开源模块，遵循这些默认设置可以确保模块与其他社区模块共享一致的编码风格，使其他人更容易贡献。

生态系统

Nuxt 模块生态系统 代表每月超过 1500 万次 NPM 下载，并提供与各种工具的扩展功能和集成。您可以成为这个生态系统的一部分！

模块类型

官方模块是以 @nuxt/ 为前缀（作用域）的模块（例如 @nuxt/content）。它们由 Nuxt 团队制作并积极维护。与框架一样，欢迎社区的贡献来帮助改进它们！

社区模块是以 @nuxtjs/ 为前缀（作用域）的模块（例如 @nuxtjs/tailwindcss）。它们是由社区成员制作和维护的成熟模块。同样，欢迎任何人的贡献。

第三方和其他社区模块是以 nuxt- 为前缀的模块（通常）。任何人都可以制作它们，使用此前缀可以使这些模块在 npm 上可发现。这是起草和尝试想法的最佳起点！

私有或个人模块是为您自己的用例或公司制作的模块。它们不需要遵循任何命名规则即可与 Nuxt 一起工作，通常在 npm 组织下进行作用域（例如 @my-company/nuxt-auth）

列出您的社区模块

欢迎任何社区模块列在模块列表上。要列出，请在 nuxt/modules 仓库中打开一个问题。Nuxt 团队可以在列出之前帮助您应用最佳实践。

加入 nuxt-modules 和 @nuxtjs/

通过将模块移动到 nuxt-modules，总会有人可以提供帮助，这样我们可以联合力量来制作一个完美的解决方案。

如果您已经发布并运行的模块，并希望将其转移到 nuxt-modules，在 nuxt/modules 中打开一个问题。

通过加入 nuxt-modules，我们可以将您的社区模块重命名为 @nuxtjs/ 作用域，并为其文档提供一个子域（例如 my-module.nuxtjs.org）。