理解模块结构

了解 Nuxt 模块的结构以及如何定义它们。

有两种类型的 Nuxt 模块：

  • 发布的模块在 npm 上分发 - 您可以在 Nuxt 网站 上查看一些社区模块列表
  • "本地"模块存在于 Nuxt 项目中，可以内联在 Nuxt 配置中或位于modules 目录中

无论哪种情况，它们都以相同的方式工作。

定义您的模块

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

模块定义是您的模块的入口点。当在 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', (nuxt) => {
    console.log('Nuxt 已就绪')
  })
}

您可以使用高级 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',
      // 默认情况下，moduleDependencies 将被添加到 Nuxt 要安装的模块列表中
      // 除非设置了 `optional`。
      optional: true,
      // 任何应该覆盖 `nuxt.options` 的配置。
      overrides: {},
      // 任何应该设置的配置。它将覆盖模块默认值但
      // 不会覆盖在 `nuxt.options` 中设置的任何配置。
      defaults: {},
    },
  },
  // 保存模块逻辑的函数，它可以是异步的
  setup (moduleOptions, nuxt) {
    // ...
  },
})

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

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

添加运行时代码

使用启动器时，运行时目录是 src/runtime/。

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

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

对于 Nitro：

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

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

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

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

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

出于性能原因，不会为 node_modules 中的文件（发布的模块最终将位于的位置）启用自动导入。

创建您的第一个模块

学习如何使用官方启动器模板创建您的第一个 Nuxt 模块。

添加插件、组件等

了解如何从您的模块注入插件、组件、组合式函数和服务器路由。