Nuxt Bridge 的 Legacy Composition API 迁移指南：从 @nuxtjs/composition-api 平滑对齐 Nuxt 3

Nuxt Bridge 的 Legacy Composition API 迁移指南从 nuxtjs/composition-api 平滑对齐 Nuxt 3【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxtNuxt Bridge 是运行在 Nuxt 2 项目上的前向兼容层模块它让你不必一次性重写整个应用就能逐步体验并迁移到 Nuxt 3 的 API 体系。本文聚焦 Bridge 中最关键的一环——如何从 Nuxt 2 时代的vue/composition-api/nuxtjs/composition-api迁移到与 Nuxt 3 完全对齐的 Composition API 语法读完你将掌握依赖清理、bridge.capi配置、各 legacy composable 的等价替换方案以及自动导入机制为最终升级到 Nuxt 3/4 扫清最大障碍。背景Bridge 与 Composition API 的位置关系在开始迁移之前先明确 Nuxt Bridge 的定位。根据 Bridge OverviewBridge 是一个前向兼容层通过安装并启用一个 Nuxt 模块即可在 Nuxt 2 项目中体验大量 Nuxt 3 特性从而让项目几乎准备好迁移到 Nuxt 3并允许你分步骤渐进式过渡。Bridge 文档将升级拆解为多个可独立执行的步骤其中与本主题直接相关的两步是Migrate Legacy Composition API即本文主题处理旧版nuxtjs/composition-api的存量代码Migrate New Composition API在清理旧代码后把关键函数替换为 Nuxt 3 风格的新 composableNuxt Bridge 提供的 Composition API 是专门与 Nuxt 3 对齐的。这意味着即使你此前已经在用 Composition API启用 Bridge 时仍有少量额外步骤——因为 Bridge 的实现与旧的nuxtjs/composition-api存在差异且提供的 composable 集合以 Nuxt 3 为准。有些旧 composable 被移除且暂无替代品因此迁移过程需要逐一处理。第一步移除旧依赖无论你之前用的是哪种 Composition API 方案首先都应从package.json与nuxt.config中移除两个旧包从依赖中移除vue/composition-api从依赖中移除nuxtjs/composition-api同时从nuxt.config的modules/buildModules中移除对应的模块声明。移除之后Composition API 的支持完全交由 Nuxt Bridge 提供不需要再手动注册任何东西详见下文。仅使用过vue/composition-api的场景几乎零成本如果你的代码只依赖vue/composition-api例如手动执行过Vue.use(VueCompositionApi)而没有使用nuxtjs/composition-api迁移会非常直接1. 删除手动注册 Composition API 的插件。这个注册工作现在由 Nuxt Bridge 自动完成你需要把形如下面的代码从插件中删掉- import Vue from vue - import VueCompositionApi from vue/composition-api - - Vue.use(VueCompositionApi)2. 除此之外无需做任何事。可选操作是删除代码中vue/composition-api的显式 import改为依赖 Nuxt Bridge 的自动导入auto-import机制——ref、computed等 Vue API 都会被自动注入。关于自动导入的完整约定可参考 Auto-imports 概念文档。这一无缝兼容的设计在当前仓库的核心实现中也能找到佐证现代 Nuxt 在初始化时会把vue-demi与vue/composition-api两个模块名直接别名alias到应用内置的 compat 目录见 packages/nuxt/src/core/nuxt.ts 中的options.alias[vue-demi]与options.alias[vue/composition-api]。别名指向的 shim 文件 packages/nuxt/src/app/compat/capi.ts 会export * from vue并额外提供install、set、del等空实现/兼容函数packages/nuxt/src/app/compat/vue-demi.ts 则直接声明isVue3 true。也就是说只要代码中保留了import { ref } from vue/composition-api这样的写法shim 也能保证其继续可用——这为从 Bridge 平滑过渡到 Nuxt 3/4 提供了一致的底层保障。从nuxtjs/composition-api迁移差异与例外与直接使用vue/composition-api不同nuxtjs/composition-api的用户会面临更多改动因为Nuxt Bridge 对 Composition API 的实现与nuxtjs/composition-api略有不同Bridge 提供的 composable 以 Nuxt 3 的 composable 集合为基准部分旧 composable 被移除且暂未提供替代品。从 buildModules 移除nuxtjs/composition-api/module你不必立即修改全部 import——在移除模块之后Nuxt Bridge 会自动为目前代码中的大多数 import 提供 shim垫片从而给你留出迁移到新 composable 的时间。但有以下几个例外它们已经被彻底移除必须手动处理withContext已移除。需要迁移到useNuxtApp/useState等新 API参见 Migrate New Composition API 中关于useContext和withContext的说明。useStatic已移除。目前没有替代品如果你确实需要它可以在社区发起 discussion 说明你的使用场景。reqRef与reqSsrRef此前已被标记为 deprecated已彻底移除。请按照下文中ssrRef/shallowSsrRef的替换指引见 Migrate New Composition API 的对应小节进行迁移。设置bridge.capi为了让 Bridge 提供 Nuxt 3 风格的 Composition API并兼容上述 legacy shim需要在nuxt.config中显式启用capi特性该特性默认开启此处为显式声明import { defineNuxtConfig } from nuxt/bridge export default defineNuxtConfig({ bridge: { capi: true, nitro: false, // 如果已完成向 Nitro 的迁移请改为 true }, })结合 Bridge Configuration 中的特性开关说明capi还支持更细粒度的控制// Disable Composition API support entirely // capi: false, // ... or just disable legacy Composition API support // capi: { // legacy: false // },也就是说bridge.capi: false会整体关闭 Composition API 支持而bridge.capi: { legacy: false }只关闭旧版nuxtjs/composition-api风格的兼容支持Nuxt 3 风格的新 API 仍然可用。此外nitro: false意味着暂用 legacy server若已完成 Nitro 迁移则设为true。其余在用的每个nuxtjs/composition-apicomposable按下面的步骤逐一替换。逐个 composable 的迁移对照useFetch$fetchState与$fetch被移除Bridge 版本不再返回$fetch与$fetchState需要改用fetch与fetchStateconst { - $fetch, - $fetchState, fetch, fetchState, } useFetch(() { posts.value await $fetch(/api/posts) })注意其中的useFetch(() ...)内部回调依然是旧式写法在回调内通过副作用给posts赋值这仅用于展示属性名变化后续若迁移到 Nuxt 3 风格的useLazyFetch/useLazyAsyncData应改为由它们返回响应式data详见 Migrate New Composition API 的useAsync/useFetch小节以及 Data Fetching 中对useAsyncData/useFetch的完整讲解。defineNuxtMiddleware类型辅助桩函数已移除defineNuxtMiddleware只是一个类型辅助的桩函数现已移除。直接去掉这一层包装- import { defineNuxtMiddleware } from nuxtjs/composition-api - export default defineNuxtMiddleware((ctx) {}) export default (ctx) {}如果需要 TypeScript 类型支持可以改用nuxt/types提供的Middleware类型import type { Middleware } from nuxt/types export default Middleware function (ctx) { }defineNuxtPlugin类型辅助桩函数已移除与defineNuxtMiddleware同理defineNuxtPlugin也是一个被移除的类型辅助桩函数。如果你希望继续使用 Nuxt 2 风格的插件去掉函数包装即可- import { defineNuxtPlugin } from nuxtjs/composition-api - export default defineNuxtPlugin((ctx, inject) {}) export default (ctx, inject) {}需要 TypeScript 支持时可用nuxt/types的Plugin类型import type { Plugin } from nuxt/types export default Plugin function (ctx, inject) {}::warning 上例虽然有效但请注意Nuxt 3 引入了签名略有不同的新defineNuxtPlugin函数。若希望一步到位迁移到 Nuxt 3 插件格式插件只接收单个nuxtApp参数请参考 Creating Plugins 文档 以及 Plugins and Middleware 迁移文档 中的新插件写法示例中使用nuxtApp.provide(injected, ...)提供可在模板/实例中以$injected访问的能力。 ::useRouter与useRoute直接替换但 route 不再是 computedBridge 为这两个 composable 提供了直接替代品useRouter与useRoute分别对应 useRouter 与 useRoute。二者之间唯一关键差异是Bridge及 Nuxt 3的useRoute()不再返回 computed 属性因此访问路径不再需要.value- import { useRouter, useRoute } from nuxtjs/composition-api const router useRouter() const route useRoute() - console.log(route.value.path) console.log(route.path)也就是说如果旧代码中存在大量route.value.xxx的访问需要全局移除.value。useRoute()返回的 route 对象本身已具备响应式属性例如动态参数、查询参数等都会随导航更新详情可阅读 useRoute API 文档。向 Nuxt 3 风格 API 迈进ssrRef、useContext等的归宿原文档中明确指出withContext、useStatic、reqRef/reqSsrRef的替代品需要参考 Migrate New Composition API。这里给出其中几项的关键迁移方向帮助你一次性规划到位ssrRef/shallowSsrRef→useState。新 composable 在底层工作方式上非常接近但你必须显式提供key旧实现会自动生成而且useState只能在组件实例或 Nuxt 3 插件defineNuxtPlugin上下文中调用不能在全局/环境上下文中使用以避免跨请求共享状态- import { ssrRef } from nuxtjs/composition-api - const ref1 ssrRef(initialData) const ref1 useState(ref1-key, () initialData) // 访问方式保持不变 console.log(ref1.value)keyed 状态意味着只要使用相同 key就能在多个位置访问同一份状态。详见 useState API 文档。useContext/useStore→useNuxtApp。通过useNuxtApp()可以访问注入的 helper如$axios与 Vuex store- import { useContext } from nuxtjs/composition-api const { $axios } useNuxtApp() - import { useStore } from nuxtjs/composition-api const { $store } useNuxtApp()另需注意useNuxtApp()还暴露一个nuxt2Contextkey包含 Nuxt 2 context 的全部属性但官方不建议直接使用它它在 Nuxt 3 中不存在应尽量寻找其他访问途径。详见 useNuxtApp API 文档。onGlobalSetup→ 插件 hook。可在defineNuxtPlugin内通过nuxtApp.hook(vue:setup, ...)实现等价逻辑也可以在 layout 的setup()中运行自定义代码。useAsync/useFetch→useLazyAsyncData/useLazyFetch。这些lazy版本与旧 composable 一样不会在客户端阻塞路由导航但 API 完全不同不要试图在 composable 外部修改其他变量。且useLazyFetch需要先启用 Nitro。useMeta→useNuxt2Meta或useHead。在 Bridge 中可继续用useNuxt2Meta以vue-meta兼容方式操作 meta支持响应式更新但 Nuxt 3 不支持也可以显式启用bridge.meta: true后使用 Nuxt 3 兼容的 useHead底层基于unhead/vue。注意不要在同一组件内混用useNuxt2Meta()与 Options API 的head()也不要混用原生 Nuxt 2 的head()属性与useHead。关于自动导入#imports与显式禁用完成上述替换后若代码中仍保留旧包的显式 import例如import { ref } from nuxtjs/composition-api建议逐步移除转而依赖 Bridge 的自动导入。与 Nuxt 3/4 一致Nuxt 也通过#imports别名暴露所有自动导入项供需要时显式引用script setup langts import { computed, ref } from #imports const count ref(1) const double computed(() count.value * 2) /script如果你想彻底关闭 composable 与工具函数的自动导入可在nuxt.config中设置imports.autoImport: false此时仍可从#imports显式导入export default defineNuxtConfig({ imports: { autoImport: false, }, })更完整的自动导入行为说明包含imports.scan等进阶选项可参考 Auto-imports 概念文档。迁移后的验证与后续升级路径完成上述改造后建议按 Bridge Overview 的指引回归验证确保 dev server 未运行将 package.json 中的脚本由nuxt切换为nuxt2例如dev: nuxt2、build: nuxt2 build、start: nuxt2 start先运行一次确认应用行为与之前一致再继续下一步。Nuxt Bridge 的整套迁移不需要一次性完成你可以按需逐项推进。与本主题衔接紧密的后续步骤包括TypeScript 迁移——先补齐类型基础Plugins and Middleware 迁移——迁移到defineNuxtPlugin/defineNuxtRouteMiddleware新格式并通过macros.pageMeta: true启用definePageMeta仅限middleware与layoutMigrate New Composition API——完成ssrRef→useState、useMeta→useNuxt2Meta/useHead等最终替换之后依次处理 Meta Tags、Runtime Config、Nitro、Vite 等选项。需要提醒的是Bridge 本质上仍运行在 Nuxt 2 之上它追求与 Nuxt 3 的特性对齐但也存在若干已知边界例如 Bridge 文档在 overview 中提示useAsyncData/useFetch等 composable 存在使用限制请以 Bridge Overview 与 Bridge Configuration 中列出的特性开关为准。因此在动手改造存量代码前先对照特性开关梳理项目中实际用到的 composable 清单能显著降低迁移过程中的返工成本。【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考