Nuxt.js 迁移指南：插件与中间件从 v2 到 v3 的演进

Nuxt.js 迁移指南：插件与中间件从 v2 到 v3 的演进

nuxt The Intuitive Vue Framework. 项目地址: https://gitcode.com/gh_mirrors/nu/nuxt

前言

在 Nuxt.js 从 v2 升级到 v3 的过程中，插件(Plugins)和中间件(Middleware)系统经历了重大重构。本文将深入解析这些变化，帮助开发者顺利完成迁移工作。

插件系统的变革

Nuxt 3 对插件系统进行了现代化改造，使其更加简洁且类型安全。

新旧对比

Nuxt 2 插件写法：

export default (ctx, inject) => {
  inject('injected', () => 'my injected function')
}

Nuxt 3 插件写法：

export default defineNuxtPlugin(nuxtApp => {
  // 方式一：直接使用 provide 方法
  nuxtApp.provide('injected', () => 'my injected function')

  // 方式二：返回 provide 对象（推荐，自动类型推导）
  return {
    provide: {
      injected: () => 'my injected function'
    }
  }
})

关键变化解析

1. 参数简化：从接收 (ctx, inject) 变为只接收 nuxtApp 对象
2. 注入方式：不再使用 inject 方法，而是使用 nuxtApp.provide() 或返回 provide 对象
3. 类型支持：返回 provide 对象的方式能获得更好的 TypeScript 类型推断

迁移实践建议

1. 使用 defineNuxtPlugin 包装所有插件
2. 移除 nuxt.config 中 plugins 数组里对 plugins/ 目录下文件的显式注册
3. 通过文件命名约定指定插件运行环境：
   • .client.ts 仅客户端运行
   • .server.ts 仅服务端运行
   • 无后缀文件则同时运行

路由中间件的进化

路由中间件在 Nuxt 3 中也经历了类似的现代化改造。

新旧对比

Nuxt 2 中间件写法：

export default function ({ store, redirect }) {
  if (!store.state.authenticated) {
    return redirect('/login')
  }
}

Nuxt 3 中间件写法：

export default defineNuxtRouteMiddleware((to, from) => {
  const auth = useState('auth')
  if (!auth.value.authenticated) {
    return navigateTo('/login')
  }
})

核心变化说明

1. 参数变化：从上下文对象变为 to 和 from 路由对象
2. 状态管理：推荐使用 useState 替代直接访问 store
3. 导航方法：redirect 改为 navigateTo
4. 注册方式：依然自动注册 ~/middleware 目录下的文件

迁移关键步骤

1. 使用 defineNuxtRouteMiddleware 包装中间件
2. 全局中间件需添加 .global 后缀，如 auth.global.ts
3. 页面级中间件通过 definePageMeta 指定，而非组件选项

最佳实践建议

1. 类型安全优先：尽可能使用返回对象的插件写法以获得完整类型支持
2. 合理拆分中间件：根据作用范围选择全局或局部中间件
3. 利用组合式API：在中间件中使用 useState 等组合式函数
4. 环境区分明确：通过文件后缀清晰表明插件运行环境

总结

Nuxt 3 对插件和中间件系统的改造使其更加现代化和类型友好。理解这些变化背后的设计理念，将帮助开发者编写出更健壮、更易维护的 Nuxt 应用。迁移过程虽然需要一些调整，但最终会带来更好的开发体验和应用性能。

nuxt The Intuitive Vue Framework. 项目地址: https://gitcode.com/gh_mirrors/nu/nuxt