理解模块结构

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

Nuxt 模块有两种类型：

已发布的模块分发在 npm 上 —— 你可以在 Nuxt 官网的模块列表中看到一些社区模块。
“本地”模块存在于 Nuxt 项目中，可能是内联在 Nuxt 配置中，也可能是在 modules 目录下。

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

定义你的模块

使用 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) {
    // ...
  },
})