模块

模块兼容性

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

我们已经准备了一个 专门指南，用于使用 @nuxt/kit 编写面向 Nuxt 3 的模块。当前最佳的迁移路径是遵循该指南并重写你的模块。本指南的其余部分包含一些准备步骤，适用于那些希望避免全面重写但又想使模块与 Nuxt 3 兼容的情况。

插件兼容性

Nuxt 3 插件并不完全向后兼容 Nuxt 2。

Vue 兼容性

使用 Composition API 的插件或组件需要专门支持 Vue 2 或 Vue 3。

通过使用 vue-demi，它们应该可以同时兼容 Nuxt 2 和 Nuxt 3。

模块迁移

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

使用 @nuxt/bridge 测试

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

如果你的模块中有示例或 fixture，请在其配置中添加 @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，因此强烈建议考虑迁移。