模块

模块兼容性

Nuxt 3 为 Nuxt 2 模块提供了基于 @nuxt/kit 自动包装器的基础向后兼容层。但通常仍需要遵循一些步骤才能使模块兼容 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 和 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，强烈建议考虑迁移。