理解模块结构

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

Nuxt 模块有两种类型：

无论哪种方式，它们的工作原理是相同的。

定义你的模块

使用 starter 时，你的模块定义位于 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 辅助函数获取此函数的类型提示，该辅助函数由 Nuxt Kit 提供。

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 版本的语义化版本号范围
      nuxt: '>=3.0.0',
    },
  },
  // 模块的默认配置选项，也可以是返回默认配置的函数
  defaults: {},
  // 注册 Nuxt 钩子的简写糖
  hooks: {},
  // 其他模块的配置 —— 这不保证其他模块在你的模块之前运行， 但允许你在它们运行前修改它们的配置
  moduleDependencies: {
    'some-module': {
      // 你可以为依赖模块指定版本约束。如果用户安装了不同版本，Nuxt 启动时会报错。
      version: '>=2',
      // 默认情况下，除非设置了 `optional`，moduleDependencies 会被添加到 Nuxt 要安装的模块列表中。
      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，就有向前和向上兼容性
  • 与模块构建工具的集成

添加运行时代码

使用 starter 时，运行时目录为 src/runtime/。

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

在 runtime 目录中，你可以提供任何与 Nuxt 应用相关的资源：

对于 服务器引擎 Nitro：

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

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

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

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

了解更多关于资源注入的信息，请查看示例章节。
已发布的模块无法对其 runtime 目录中的资源使用自动导入。它们必须显式地从 #imports 等处导入。

出于性能考虑，自动导入不对 node_modules（即已发布模块所在的位置）中的文件启用。