通过 100 多个技巧学习 Nuxt!

模块

了解如何将 Nuxt 2 模块迁移到 Nuxt 3。

模块兼容性

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

我们准备了一份专用指南,介绍如何使用 @nuxt/kit 编写与 Nuxt 3 兼容的模块。目前最好的迁移路径是遵循该指南并重写您的模块。本指南的其余部分包括准备步骤,如果您希望避免完全重写,但仍希望模块与 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 的第一个也是最重要的步骤。

如果您的模块中有 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)

避免运行时模块

对于 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 被设计为渐进式的!
您可以将 TypeScript 语法用于 Nuxt 2 和 3 模块和插件,而无需任何额外的依赖项。