Question

Module Compatibility

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

我们已经准备了一份 专用指南，用于使用 @nuxt/kit 编写 Nuxt 3 就绪模块。 目前最好的迁移路径是遵循它并重写你的模块。 如果您希望避免完全重写但使模块与 Nuxt 3 兼容，则本指南的其余部分包括准备步骤。

您可以从 Nuxt Modules 查看 Nuxt 3 就绪模块列表。

插件兼容性

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

使用 @nuxt/bridge 进行测试

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

如果您的模块中有夹具或示例，请将“@nuxt/bridge”包添加到其配置中

从 CommonJS 迁移到 ESM

Nuxt 3 原生支持 TypeScript 和 ECMAScript 模块。 请查看 Native ES Modules 了解更多信息和升级。

确保插件默认导出

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

Before

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

Vue.use(Vuelidate)

After

// ~/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) { } 保护。

继续阅读 模块指南 中有关 Nuxt 3 模块的信息。

使用 TypeScript（可选）

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

您可以通过将 .js 文件重命名为 .ts 来开始迁移。 TypeScript 被设计成渐进式的！

您可以对 Nuxt 2 和 3 模块和插件使用 TypeScript 语法，而无需任何额外的依赖项。