模块作者指南

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

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

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

快速开始

我们推荐使用我们的 starter template 来开始编写 Nuxt 模块：

npm create nuxt -- -t module my-module

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

下一步：

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

使用启动模板

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

观看 Vue School 关于 Nuxt 模块启动模板的视频。

如何开发

尽管你的模块源代码位于 src 目录，但在大多数情况下，为了开发模块，你需要一个 Nuxt 应用。这就是 playground 目录的作用。它是一个你可以随意测试的 Nuxt 应用，已配置为与您的模块一起运行。

你可以像操作任何 Nuxt 应用一样与 playground 交互。

  • 使用 npm run dev 启动其开发服务器，当你对 src 目录中的模块进行更改时，它应会自动重新加载
  • 使用 npm run dev:build 构建它
所有其他 nuxt 命令也可以针对 playground 目录使用（例如 nuxt <COMMAND> playground）。也可以在 package.json 中声明额外的 dev:* 脚本以便使用。

如何测试

模块启动模板附带了一个基本的测试套件：

  • 由 ESLint 提供的 linter，可通过 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 运行发布脚本。

运行发布脚本时，将发生以下操作：

  • 首先，它将运行你的测试套件：
    • 运行 linter（npm run lint）
    • 运行单元、集成和 e2e 测试（npm run test）
    • 构建模块（npm run prepack）
  • 然后，如果测试套件通过，它将继续发布你的模块：
    • 根据你的 Conventional Commits 提升模块版本并生成变更日志
    • 将模块发布到 npm（为此，模块将再次构建以确保已更新的版本号包含在发布产物中）
    • 将代表新发布版本的 git 标签推送到你的 git 远程 origin
与其他脚本一样，可以根据需要微调 package.json 中的默认 release 脚本。

开发模块

Nuxt 模块提供了多种强大的 API 和模式，允许它们以几乎任何可能的方式改变 Nuxt 应用。本节将教你如何利用这些功能。

模块结构

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

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

模块定义

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

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

在底层，Nuxt 模块定义是一个简单的、可能是异步的函数，接受内联用户选项和一个用于与 Nuxt 交互的 nuxt 对象。

export default function (inlineOptions, nuxt) {
  // You can do whatever you like here..
  console.log(inlineOptions.token) // `123`
  console.log(nuxt.options.dev) // `true` or `false`
  nuxt.hook('ready', (nuxt) => {
    console.log('Nuxt is ready')
  })
}

你可以使用 Nuxt Kit 提供的更高层次的 defineNuxtModule 帮助方法为此函数获得类型提示支持。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook('pages:extend', (pages) => {
    console.log(`Discovered ${pages.length} pages`)
  })
})

然而，我们不建议使用这种底层的函数定义。相反，定义模块时，我们推荐使用带有 meta 属性的对象语法来标识你的模块，尤其是在发布到 npm 时。

该帮助函数通过实现模块所需的许多常见模式，使编写 Nuxt 模块更简单，保证将来的兼容性并改善模块作者和用户的体验。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    // Usually the npm package name of your module
    name: '@nuxtjs/example',
    // The key in `nuxt.config` that holds your module options
    configKey: 'sample',
    // Compatibility constraints
    compatibility: {
      // Semver version of supported nuxt versions
      nuxt: '>=3.0.0',
    },
  },
  // Default configuration options for your module, can also be a function returning those
  defaults: {},
  // Shorthand sugar to register Nuxt hooks
  hooks: {},
  // Configuration for other modules - this does not ensure the module runs before
  // your module, but it allows you to change the other module's configuration before it runs
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module. If the user has a different
      // version installed, Nuxt will throw an error on startup.
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules to be installed
      // by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {},
    },
  },
  // The function holding your module logic, it can be asynchronous
  setup (moduleOptions, nuxt) {
    // ...
  },
})

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

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

运行时目录

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

模块（像 Nuxt 配置中的其他内容一样）不会包含在应用运行时中。但是，你可能希望你的模块为其被安装的应用提供或注入运行时代码。运行时目录就是为此提供支持的。

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

对于 服务端引擎，Nitro：

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

或者任何你想注入到用户 Nuxt 应用的其他类型资源：

  • 样式表
  • 3D 模型
  • 图像
  • 等等。

然后你可以从你的 模块定义 中将所有这些资源注入到应用中。

在 recipes 部分 中了解有关资源注入的更多信息。
已发布的模块无法对其运行时目录内的资源使用自动导入。相反，它们必须显式地从 #imports 或类似位置导入。

这是因为出于性能原因，自动导入不会对位于 node_modules（已发布模块最终所在位置）内的文件启用。

工具链

模块附带了一组一方工具来帮助开发。

@nuxt/module-builder

Nuxt Module Builder 是一个零配置的构建工具，负责构建和发布模块所需的繁杂工作。它确保你的模块构建产物与 Nuxt 应用的正确兼容性。

@nuxt/kit

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

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

@nuxt/test-utils

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

Recipes（使用示例）

在此处找到用于编写模块的常见模式。

更改 Nuxt 配置

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

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // We create the `experimental` object if it doesn't exist yet
    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 来扩展用户提供的公共运行时配置，而不是覆盖它。

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

import { useRuntimeConfig } from '@nuxt/kit'

const options = useRuntimeConfig().public.myModule
请注意不要在公共运行时配置中暴露任何敏感的模块配置，例如私有 API 密钥，因为它们会出现在公共包中。
Read more in Docs > 4 X > Guide > Going Further > Runtime Config.
观看 Vue School 关于传递和暴露 Nuxt 模块选项的视频。

使用 addPlugin 注入插件

插件是模块添加运行时逻辑的常用方式。你可以使用 addPlugin 实用工具从模块中注册它们。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // Create resolver to resolve relative paths
    const resolver = createResolver(import.meta.url)

    addPlugin(resolver.resolve('./runtime/plugin'))
  },
})
Read more in Docs > 4 X > Guide > Going Further > Kit.

使用 addComponent 注入 Vue 组件

如果你的模块应该提供 Vue 组件，可以使用 addComponent 实用工具将它们作为 Nuxt 的自动导入注册。

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

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

    // From the runtime directory
    addComponent({
      name: 'MySuperComponent', // name of the component to be used in vue templates
      export: 'MySuperComponent', // (optional) if the component is a named (rather than default) export
      filePath: resolver.resolve('runtime/components/MySuperComponent.vue'),
    })

    // From a library
    addComponent({
      name: 'MyAwesomeComponent', // name of the component to be used in vue templates
      export: 'MyAwesomeComponent', // (optional) if the component is a named (rather than default) export
      filePath: '@vue/awesome-components',
    })
  },
})

另外，你可以使用 addComponentsDir 添加整个目录。

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

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

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

使用 addImports 和 addImportsDir 注入 Composables

如果你的模块应该提供 composables，可以使用 addImports 实用工具将它们作为 Nuxt 的自动导入注册。

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

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

    addImports({
      name: 'useComposable', // name of the composable to be used
      as: 'useComposable',
      from: resolver.resolve('runtime/composables/useComposable'), // path of composable
    })
  },
})

或者，你可以使用 addImportsDir 添加整个目录。

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

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

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

使用 addServerHandler 注入服务端路由

import { addServerHandler, createResolver, defineNuxtModule } 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 { addServerHandler, createResolver, defineNuxtModule } 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 { addPlugin, createResolver, defineNuxtModule } 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 { createResolver, defineNuxtModule } from '@nuxt/kit'

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

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

在模块中使用其他模块

如果您的模块依赖于其他模块，您可以使用 moduleDependencies 选项指定它们。这提供了一种更强大的方式来处理具有版本约束和配置合并的模块依赖关系：

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

const resolver = createResolver(import.meta.url)

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    '@nuxtjs/tailwindcss': {
      // You can specify a version constraint for the module
      version: '>=6',
      // Any configuration that should override `nuxt.options`
      overrides: {
        exposeConfig: true,
      },
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`
      defaults: {
        config: {
          darkMode: 'class',
          content: {
            files: [
              resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
              resolver.resolve('./runtime/*.{mjs,js,ts}'),
            ],
          },
        },
      },
    },
  },
  setup (options, nuxt) {
    // We can inject our CSS file which includes Tailwind's directives
    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
  },
})
moduleDependencies 选项替代了已弃用的 installModule 函数，并确保正确的设置顺序和配置合并。

使用钩子

生命周期钩子 允许您扩展 Nuxt 的几乎每个方面。模块可以通过编程方式或通过其定义中的 hooks 映射来挂钩。

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

export default defineNuxtModule({
  // Hook to the `app:error` hook through the `hooks` map
  hooks: {
    'app:error': (err) => {
      console.info(`This error happened: ${err}`)
    },
  },
  setup (options, nuxt) {
    // Programmatically hook to the `pages:extend` hook
    nuxt.hook('pages:extend', (pages) => {
      console.info(`Discovered ${pages.length} pages`)
    })
  },
})
Read more in Docs > 4 X > API > Advanced > Hooks.
观看 Vue School 关于在模块中使用 Nuxt 生命周期钩子的视频。
模块清理

如果你的模块打开、处理或启动了一个 watcher，你应该在 Nuxt 生命周期结束时将其关闭。可以使用 close 钩子来完成此操作。
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async (nuxt) => {
      // Your custom code here
    })
  },
})
自定义钩子

模块还可以定义并调用它们自己的钩子，这是使模块可扩展的强大模式。

如果你希望其他模块能够订阅你的模块钩子，应在 modules:done 钩子中调用它们。这可确保所有其他模块都有机会在它们自己的 setup 函数期间设置并注册对你钩子的监听器。

// 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) {
    // Call your hook in `modules:done`
    nuxt.hook('modules:done', async () => {
      const payload = { foo: 'bar' }
      await nuxt.callHook('my-module:custom-hook', payload)
    })
  },
})

添加模板/虚拟文件

如果你需要添加可以被用户应用导入的虚拟文件，可以使用 addTemplate 实用工具。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // The file is added to Nuxt's internal virtual file system and can be imported from '#build/my-module-feature.mjs'
    addTemplate({
      filename: 'my-module-feature.mjs',
      getContents: () => 'export const myModuleFeature = () => "hello world !"',
    })
  },
})

对于服务器端，你应该使用 addServerTemplate 实用工具。

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

export default defineNuxtModule({
  setup (options, nuxt) {
    // The file is added to Nitro's virtual file system and can be imported in the server code from 'my-server-module.mjs'
    addServerTemplate({
      filename: 'my-server-module.mjs',
      getContents: () => 'export const myServerModule = () => "hello world !"',
    })
  },
})

更新模板

如果您需要更新您的模板/虚拟文件，可以像下面这样使用 updateTemplates 工具：

nuxt.hook('builder:watch', (event, path) => {
  if (path.includes('my-module-feature.config')) {
    // This will reload the template that you registered
    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
  }
})

添加类型声明

你可能还想向用户项目添加类型声明（例如，扩展 Nuxt 的接口或提供你自己的全局类型）。为此，Nuxt 提供了 addTypeTemplate 实用工具，它既会将模板写入磁盘，也会将其引用添加到生成的 nuxt.d.ts 文件中。

如果你的模块应扩展 Nuxt 处理的类型，可以使用 addTypeTemplate 来执行此操作：

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

export default defineNuxtModule({
  setup (options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `// Generated by 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({ /* template options */ })
nuxt.hook('prepare:types', ({ references }) => {
  references.push({ path: template.dst })
})

扩展 tsconfig.json

有多种方法可以从你的模块扩展用户项目的 TypeScript 配置。

最简单的方法是直接修改 Nuxt 配置，如下所示：

// extend tsconfig.app.json
nuxt.options.typescript.tsConfig.include ??= []
nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.shared.json
nuxt.options.typescript.sharedTsConfig.include ??= []
nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.node.json
nuxt.options.typescript.nodeTsConfig.include ??= []
nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.server.json
nuxt.options.nitro.typescript ??= {}
nuxt.options.nitro.typescript.tsConfig ??= {}
nuxt.options.nitro.typescript.tsConfig.include ??= []
nuxt.options.nitro.typescript.tsConfig.include.push(resolve('./augments.d.ts'))

或者，您可以使用 prepare:types 和 nitro:prepare:types 钩子来扩展特定类型上下文的 TypeScript 引用，或者像上面的示例一样修改 TypeScript 配置。

nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
  // extend app context
  references.push({ path: resolve('./augments.d.ts') })
  // extend shared context
  sharedReferences.push({ path: resolve('./augments.d.ts') })
  // extend node context
  nodeReferences.push({ path: resolve('./augments.d.ts') })
})

nuxt.hook('nitro:prepare:types', ({ references }) => {
  // extend server context
  references.push({ path: resolve('./augments.d.ts') })
})

测试

测试有助于确保你的模块在各种设置下按预期工作。本节介绍如何对模块执行各种测试。

单元和集成测试

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

查看此 RFC 并参与讨论。

端到端测试

Nuxt Test Utils 是帮助你以端到端方式测试模块的首选库。推荐的工作流程如下：

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

在实践中，fixture：

test/fixtures/ssr/nuxt.config.ts
// 1. Create a Nuxt application to be used as a "fixture"
import MyModule from '../../../src/module'

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

以及它的测试：

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

describe('ssr', async () => {
  // 2. Setup Nuxt with this fixture inside your test file
  await setup({
    rootDir: fileURLToPath(new URL('./fixtures/ssr', import.meta.url)),
  })

  it('renders the index page', async () => {
    // 3. Interact with the fixture using utilities from `@nuxt/test-utils`
    const html = await $fetch('/')

    // 4. Perform checks related to this fixture
    expect(html).toContain('<div>ssr</div>')
  })
})

// 5. Repeat
describe('csr', async () => { /* ... */ })
此类工作流程的示例可在 module starter 中找到。

使用 Playground 和外部项目进行手动 QA

在开发模块时拥有一个 playground Nuxt 应用来测试你的模块非常有用。模块启动模板为此集成了 playground。

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

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

最佳实践

强大的功能也带来了责任。尽管模块功能强大，但在编写模块时请记住以下最佳实践，以保持应用性能并提升开发者体验。

异步模块

如前所述，Nuxt 模块可以是异步的。例如，你可能希望开发一个需要从某个 API 获取数据或调用异步函数的模块。

但是，要小心异步行为，因为 Nuxt 会在进入下一个模块并启动开发服务器、构建过程等之前等待你的模块完成设置。尽量将耗时操作延迟到 Nuxt 钩子中。

如果你的模块设置时间超过 1 秒，Nuxt 将对此发出警告。

始终为暴露的接口添加前缀

Nuxt 模块应为任何暴露的配置、插件、API、composable 或组件提供显式前缀，以避免与其他模块或内部冲突。

理想情况下，你应使用模块名称作为前缀（例如，如果你的模块名为 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) {
    // One-time setup: create database schema, generate config files, etc.
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (options, nuxt, previousVersion) {
    // Handle version-specific migrations
    if (semver.lt(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // Regular setup logic that runs on every build
    addServerHandler({ /* ... */ })
  },
})

此模式可防止每次构建时执行不必要的工作并提供更好的开发者体验。有关更多详细信息，请参阅生命周期钩子文档。

友好地支持 TypeScript

Nuxt 对 TypeScript 提供一流集成，以获得最佳开发者体验。

暴露类型并使用 TypeScript 开发模块，即使用户不直接使用 TypeScript，也会为他们带来好处。

避免 CommonJS 语法

Nuxt 依赖原生 ESM。有关更多信息，请阅读 Native ES Modules。

文档化模块用法

考虑在 README 文件中记录模块用法：

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

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

提供 StackBlitz 示例或样板

最好提供一个使用你的模块并附带 StackBlitz 的最小复现示例，并将其添加到模块 README 中。

这不仅为潜在用户提供了一个快速且易于实验的途径，也为他们在遇到问题时提供了一个可以发送给你的最小复现示例的简单方式。

不要用特定的 Nuxt 版本进行宣传

Nuxt、Nuxt Kit 和其他新工具均考虑了向前和向后兼容性。

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

保持使用启动模板的默认配置

模块启动模板附带了一组默认工具和配置（例如 ESLint 配置）。如果你计划将模块开源，保持这些默认设置可以确保你的模块与其他社区模块 共享一致的代码风格，从而更容易让其他人贡献。

生态系统

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

观看 Vue School 关于 Nuxt 模块类型的视频。

模块类型

官方模块 是以 @nuxt/ 为前缀（或作用域）的模块（例如 [@nuxt/content](https://content.nuxt.com））。它们由 Nuxt 团队制作并积极维护。像框架一样，社区的贡献也非常受欢迎，以帮助改进这些模块！

社区模块 是以 @nuxtjs/ 为前缀（或作用域）的模块（例如 [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org））。它们是由社区成员制作并维护的成熟模块。同样，任何人都可以贡献。

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

私有或公司内部模块 是为你自己的用例或公司制作的模块。它们不需要遵循任何命名规则即可与 Nuxt 一起工作，通常以 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）。