模块

模块兼容性

Nuxt 3 为 Nuxt 2 模块提供了一个基本的向后兼容层，使用的是 @nuxt/kit 自动包装器。但通常需要遵循一些步骤以使模块兼容 Nuxt 3，有时还需要使用 Nuxt Bridge 来实现跨版本兼容性。

我们为使用 @nuxt/kit 编写 Nuxt 3 兼容模块准备了一个 专门指南。目前最好的迁移路径是按照它进行模块重写。如果您更倾向于避免全面重写，以下指南还包括了一些准备步骤，使模块兼容 Nuxt 3。

插件兼容性

Nuxt 3 插件与 Nuxt 2 的兼容性 并不完全。

Vue 兼容性

使用组合 API 的插件或组件需要独立支持 Vue 2 或 Vue 3。

通过使用 vue-demi，它们应能兼容 Nuxt 2 和 Nuxt 3。

模块迁移

当 Nuxt 3 用户添加您的模块时，您将无法访问模块容器 (this.*)，因此需要使用 @nuxt/kit 的工具来访问容器功能。

使用 @nuxt/bridge 进行测试

迁移到 @nuxt/bridge 是支持 Nuxt 3 的第一步也是最重要的一步。

如果您的模块中包含固定装置或示例，请在其配置中添加 @nuxt/bridge 包（参见 示例）。

从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript 模块。请查看 原生 ES 模块 以获取更多信息和升级说明。

确保插件默认导出

如果您注入的 Nuxt 插件没有 export default（例如全局 Vue 插件），请确保在其末尾添加 export default () => { }。

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }

避免运行时模块

在 Nuxt 3 中，Nuxt 现在是一个仅在构建时依赖的框架，这意味着模块不应尝试挂钩到 Nuxt 运行时。

您的模块应能正常工作，即使它仅添加到 buildModules（而不是 modules）。例如：

• 避免在 Nuxt 模块中更新 process.env，并通过 Nuxt 插件读取；请改用 runtimeConfig。
• (*) 避免在生产环境中依赖像 vue-renderer:* 这样的运行时钩子。
• (*) 避免通过在模块内部导入来添加 serverMiddleware。相反，请通过引用文件路径来添加，以便它们独立于模块的上下文。

(*) 除非它仅用于 nuxt dev 目的，并受到 if (nuxt.options.dev) { } 的保护。

使用 TypeScript（可选）

尽管这不是必需的，但大多数 Nuxt 生态系统正在转向使用 TypeScript，因此强烈建议考虑迁移。