老旧项目迁移到 Vue 3 的关键是可控分层：先用 @vue/compat 兜底运行，再通过 vue-codemod 自动化转换语法与 API，渐进式重构非核心模块，最后移除兼容层切换为纯 Vue 3。
老旧项目平滑迁移到 Vue 3，关键不在“一步到位”，而在“可控分层”——用兼容层兜底、自动化工具减负、模块化推进验证。直接替换 vue@2 为 vue@3 并不可行，必须借助迁移构建版本 + codemod 工具 + 双模环境协同发力。
启用 @vue/compat 迁移构建版本，先跑起来再升级
这是老旧项目最稳妥的起点。它不是最终目标，而是运行时“翻译器”：Vue 3 内核 + Vue 2 行为语义，所有废弃 API（如 $on/$off/$emit、filters、beforeDestroy）调用会触发控制台警告，但不中断执行。
- 安装迁移构建：
npm install vue@next @vue/compat - 在入口文件（如 main.js）中替换 import：
import { createApp } from 'vue'→import { createApp } from '@vue/compat' - 启用严格模式（可选）：在 createApp 后添加
app.config.compatConfig = { MODE: 2 }，让警告更密集，暴露更多潜在问题 - 注意限制：IE11 不支持；Vuetify/Element UI 等老 UI 库需确认已发布 Vue 3 版本，否则可能报 VNode 私有属性错误
用 vue-codemod 批量处理语法与 API 层级变更
人工改 Vue.extend、new Vue()、Vue.set 等是低效且易漏的。vue-codemod 基于 AST 分析，精准识别并转换，覆盖 90% 以上基础重构场景。
vue-composition-api-best-practices
下载
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
- 全局 API 迁移：
npx vue-codemod ./src -t new-global-api→ 替换import Vue from 'vue'为命名空间导入，Vue.config.xxx转为 app 实例配置 - 组件定义升级：
npx vue-codemod ./src/components -t define-component→ 将export default Vue.extend({})转为defineComponent({})，自动补全import { defineComponent } from 'vue' - 路由与状态管理：
npx vue-codemod ./src/router -t vue-router-v4和npx vue-codemod ./src/store -t vuex-4→ 处理new Router→createRouter、new Vuex.Store→createStore等 - 加
--dry参数预览效果，确认无误后再执行真实转换
渐进式重构：从非核心模块开始，逐步替换架构依赖
不要一上来就动登录页或权限系统。优先选择逻辑独立、无副作用、测试覆盖率高的模块（如 LoadingSpinner、Pagination、TableHeader），用组合式 API 重写，并接入 Pinia 替代局部 event bus。
立即学习“前端免费学习笔记（深入）”；
- 新建
src/composables/useUser.ts封装用户相关逻辑，替代this.$bus.$on('user:update')订阅 - 将旧
router/index.js拆为router/modules/user.ts+router/modules/order.ts，适配 Vue Router 4 的懒加载和嵌套路由写法 - 对 Element UI 组件，按需引入 Element Plus 对应组件，并用
v-model:value替代v-model（Vue 3 默认 prop 名变更） - 每完成一个模块，就在 compat 模式下完整走一遍用户路径，验证数据流、事件响应、样式渲染是否一致
收口：移除兼容层，切换为纯 Vue 3 运行时
当所有警告清零、所有模块完成组合式重写、Pinia / Router 4 / Element Plus 全面落地后，才进入最后一步。
- 删除
@vue/compat，改回import { createApp } from 'vue' - 清理
app.config.compatConfig配置 - 移除所有
beforeDestroy、filters、scopedSlots等 Vue 2 专属写法 - 启用
<script setup></script>语法糖，简化组件导出逻辑 - 用 Volar 替代 Vetur，确保 TypeScript 类型推导准确
