跳到主要内容
Nuxt 中文
开始使用

理解模块结构

学习 Nuxt 模块是如何构成的，以及如何定义它们。

Nuxt 模块有两种类型：

无论哪种情况，它们的工作方式都一样。

定义你的模块

使用启动模板时，你的模块定义在 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 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: {
    // 通常是你模块的 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`，否则 moduleDependencies 会被添加到
      // 待安装模块列表中
      optional: true,
      // 任何应覆盖 `nuxt.options` 的配置
      overrides: {},
      // 任何应设置的配置。它会覆盖模块默认值，但
      // 不会覆盖在 `nuxt.options` 中设置的任何配置
      defaults: {},
    },
  },
  // 包含你模块逻辑的函数，可以是异步的
  setup (moduleOptions, nuxt) {
    // ...
  },
})

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

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

添加运行时代码

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

模块就像 Nuxt 配置中的其它一切，并不包含在你应用的运行时中。然而，你可能希望你的模块向它所安装的应用提供或注入运行时代码。这就是运行时目录让你能做到的事情。

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

对于服务端引擎 Nitro：

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

或任何你想注入到用户 Nuxt 应用中的其它资源：

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

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

在配方章节 中了解更多关于资源注入的内容。
已发布的模块无法为其运行时目录中的资源利用自动导入。相反，它们必须从 #imports 或类似路径显式导入。 ::br
出于性能原因，自动导入在 node_modules 中的文件（已发布模块最终所在的位置）不会启用。