理解模块结构

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

Nuxt 模块有两种类型

发布版模块通过 npm 分发 - 你可以在 Nuxt 官网上查看一些社区模块列表。
“本地”模块存在于 Nuxt 项目内部，既可以直接内联在 Nuxt 配置中，也可以位于 modules 目录内。

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

定义你的模块

使用入门模板时，你的模块定义位于 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) {
    // ...
  },
})