把一个有 331 个 .vue 组件、仍在持续迭代的管理后台从 Vue 2 迁到 Vue 3，最危险的想法是：
“把依赖升级完，再把报错逐个修掉。”真正的迁移对象并不只有 Vue，而是路由、状态管理、UI 库、
表格封装、构建链、测试和数百个已经被用户使用的交互。
这次升级实际上分成了两段：先将 Vue 2.x + Vue CLI 迁到 Vue 2.7 + Rsbuild 并上线；随后让它在线上
稳定运行约半年，在这段时间持续清理技术债、删除不再需要的代码、尽量精简实现；最后才将已经稳定的
Vue 2.7 应用升级到 Vue 3。第二段在专用分支中阶段化完成，旧版本继续承接发布，迁移版本验收后再
整体切换。它没有演变成业务重写，也没有趁机换 Pinia 或 Vite；这份克制比任何 API 转换技巧都更重要。
| 阶段 | 主要工作 | 结束条件 |
|---|
| 第一段：构建迁移 | Vue CLI → Vue 2.7 + Rsbuild，保持业务行为 | 新构建链上线并稳定运行 |
| 稳定与清债期 | 熟悉业务边界，删除无用代码，使用跨 Vue 2.7 / Vue 3 的 API | 业务边界逐步明确，待迁移代码范围收敛 |
| 第二段：运行时迁移 | Vue 3、Router 4、Element Plus、VXE Table 4 与测试体系升级 | 移除兼容层，完成自动化与手工验收 |
第一段：先把构建系统换掉，再给业务留出稳定期
第一段从 Vue CLI 5 迁到 Rsbuild 时，应用仍运行在 Vue 2.7。目标不是借机升级框架，而是将构建链
现代化并消除已经没有价值的历史配置：移除 Vue CLI 及其插件、删除 vue.config.js 等旧配置，改用
rsbuild.config.mjs；SVG 从不兼容 Rspack 的 svg-sprite-loader 改为原生 asset/source 加载，
组件的使用方式保持不变。
采用这条路线也有现实原因：接手时我对这个项目并不熟悉，手上缺少完整的业务与技术文档。此时若同时
替换构建器、运行时、组件库并修改业务逻辑，任何异常都很难回答“它来自旧行为、构建链、Vue 3，还是
我尚未理解的业务规则”。先把范围收缩为 Vue 2.7 + Rsbuild 上线，才能在不改变主要业务语义的前提下
建立对系统的认识。
这次迁移也统一了浏览器端环境变量边界。业务代码从 process.env.VUE_APP_* 改为
import.meta.env.VUE_APP_*；少数第三方包所需的 process.env 则只在构建配置中提供兼容 shim。
这样既避免浏览器里的 process is not defined，也不需要为了兼容旧写法继续在业务代码中传播
Node.js 运行时假设。
Rsbuild 上线后，项目在 Vue 2.7 状态继续正常迭代约半年。这段稳定期的重点不是继续验证已经上线的
构建工具，而是让团队通过日常需求和真实业务流程，逐步确认业务边界与历史行为。在这个过程中，团队
持续清理技术债、删除非必要代码，让后续需要维护和迁移的范围更小、更清晰。等到 Vue 3 迁移启动时，
面对的是一套业务基线清楚、代码范围已经收敛的系统，不再需要一边迁移一边猜测旧逻辑。
这也是两段式路线最大的收益——先完成构建工具切换，再留出理解业务和收敛代码的稳定阶段，避免把
构建系统变化、Vue 运行时升级和组件库替换压在同一批改动中。第二阶段因此可以把注意力集中在 Vue 3
迁移本身。
Vue 2.7 不是终点，而是 Vue 3 的预备跑道
这半年的重构并非只做删除。Vue 2.7 原生提供了 Composition API，因此在新增或调整逻辑时，优先选用
ref、reactive、computed、watch、onMounted 等 Vue 2.7 与 Vue 3 都支持的能力；保留既有
Options API，但不再继续扩散只服务于 Vue 2 的写法。这样做不会改变已经稳定的页面风格，却能让每一次
局部维护都向 Vue 3 靠近。
this.$set 是典型例子。Vue 2 需要它来让新增对象属性或数组索引更新具备响应式；Vue 3 基于 Proxy，
普通赋值已经会响应。预备期内，改到相关代码时就倾向写成 object[key] = value 或
array[index] = value，而不是继续引入 $set。这既减少了后续迁移的工作量，也让代码表达的意图更
直接。
ESLint 在这个过程中承担的是“逐步收紧的迁移护栏”，而不是一次性把历史代码全部打红。Vue 2.7 阶段，
为避免存量项目立刻被遗留写法阻断，曾对 v-bind.sync、$set / $delete 相关的废弃规则保留豁免；
同时约束新增或重构代码不要继续引入这些 Vue 2 专属模式。正式切到 Vue 3 后，配置目标才改为 Vue 3.5
并移除豁免，让 lint 明确报出 .sync、旧销毁生命周期、.native、$listeners 等不再可用的写法，
而不是让它们在运行时才暴露。
这条护栏最终找出了 18 个文件中的 48 处 $set 调用，并将它们全部替换为普通对象或数组赋值；项目里
没有实际的 $delete 调用。14 个文件中的 20 处 .native 以及 destroyed / beforeDestroy 生命周期，
则属于切换到 Vue 3 运行时之后才能处理的破坏性变更：它们分别改为 Vue 3 的事件透传方式和
unmounted / beforeUnmount。后者不能提前放进 Vue 2.7 代码库。重要的不是这些数字本身，而是节奏：
先让新的维护代码不再制造 Vue 2 专属债务，再在运行时切换后用规则集中清理只能由 Vue 3 支持的写法。
插槽也遵循同一原则。Vue 2.7 已支持 Vue 3 使用的 v-slot / # 语法，因此在持续重构中，模板插槽
应从旧的 slot="name"、slot-scope="scope" 迁向 #name="scope"。例如：
<!-- Vue 2 旧写法：Vue 3 不支持 -->
<template slot="default" slot-scope="scope">
{{ scope.row.name }}
</template>
<!-- Vue 2.7 与 Vue 3 都支持 -->
<template #default="scope">
{{ scope.row.name }}
</template>
不过这不是一次安全的全文替换。全仓检索到 122 个 slot="..." 命中，其中混有真正需要迁移的模板、
JSX render 中合法的 slot 属性，以及注释里的死代码。正确做法是先让新增和改动的模板采用
v-slot，再在 Vue 3 阶段逐个分类处理存量命中；把 JSX 一并替换反而会制造新的问题。
AI 的角色：先生成可审查的计划，再分批执行
全仓盘点完成后，Fable 5 基于已核实的依赖、特殊用法和范围边界生成迁移 PRD；Opus 4.7 与 Sonnet 5
再按阶段、任务批次和验证门槛实施。Claude Code 则把手工验收中发现的现象、根因和规则持续沉淀到
迁移记录与项目记忆中。AI 加速了盘点、模式化修改与信息整理，但每一个结论仍须由代码、测试、构建
结果或手工观察验证。
这套协作方式、一次路由参数误判造成的回归，以及自动化和人工验收如何互补，详见
AI 参与生产系统迁移：把模型能力放进可验证的交付流程。
先做选择：为什么不是长期渐进迁移
进入第二段时，项目已经是 Vue 2.7、Vue Router 3、Vuex 3、Element UI 2、VXE Table 3、
vue-i18n 8 和 Rsbuild 的组合。目标是 Vue 3.5、Vue Router 4、Vuex 4、Element Plus、VXE Table 4
和 vue-i18n 9，同时保留已经稳定的 Rsbuild 与既有 Vuex 模块结构。
一开始看起来有三条路：全量重写、长期使用 @vue/compat 渐进迁移，或用微前端让两套运行时并行。
最后都不适合这个项目：
- 331 个组件的全量重写会把业务回归风险推到最高；
- 在本项目中，Element UI 2 与 VXE Table 3 不具备可作为发布形态的 Vue 3/compat 支持，两项核心 UI/表格依赖仍须整体迁至对应的 Vue 3 版本；
- 管理后台共享登录态、布局、权限与路由，专门建设微前端的成本远高于收益。
于是选择“阶段化的一次性迁移”。@vue/compat 只在中间阶段以 MODE 2 运行，用运行时警告当作
迁移待办扫描器；发布前必须移除。这个边界很关键：兼容层可以帮助发现问题，但不能成为问题被搁置的
理由。
先固定什么都不改时的基线
迁移第一步不是改 main.js，而是建立可回归的事实基线。
项目先补齐并跑通 Playwright 冒烟链路：登录、Dashboard、Campaign 列表和分页、报表、组织管理
弹窗。它们覆盖了权限路由、VXE Table、Element UI 表单和常见异步请求。与此同时，用
pnpm analyze 记录生产包体：迁移前未压缩总大小为 15345.0 kB，gzip 后为 7397.6 kB。
这份基线让后续每一个“看起来像 Vue 3 问题”的现象都有判断依据：它是原有问题、迁移回归，还是
尚未覆盖的新路径。没有它，构建通过只会给人错误的安全感。
分阶段切换：先打通运行时，再迁业务
迁移没有按目录从上到下改，而是按依赖关系推进。
第一阶段替换框架基础设施：Rsbuild 的 Vue 2 插件换成 Vue 3 插件，new Vue() 改为
createApp()，Vue.prototype 改到 app.config.globalProperties，路由切到
createRouter() / createWebHistory()，并将动态路由注册从 addRoutes 改为逐条 addRoute。
Vuex 3 升 Vuex 4 后，已有五个 namespaced 模块的业务 API 基本不需要改；vue-i18n 9 则采用
legacy 模式，降低了模板国际化调用的改造量。
第二阶段才整体替换第三方库：Element UI → Element Plus，VXE Table 3 → 4，并接入与 Element
Plus 对应的 VXE 渲染插件。紧接着处理 Vue 3 的机械性变化，例如 .sync 改 v-model:prop、
指令钩子改名、过时插槽语法、$listeners、$scopedSlots 和 test-utils v2 的配置变化。
机械替换也有边界。全仓有 151 处 .sync，可以分批转换并结合 diff 与构建检查；但 slot="..."
命中了 122 个文件，其中既有待迁的模板语法，也有合法的 JSX 属性和注释。对它全局替换会直接破坏
代码。类似地，路由守卫、全局指令、BiuTable / selectgrid 这类 VXE Table 深度封装，以及
BiuDialog / BiuForm 这样的基础组件，都必须按实际行为人工审查。
业务页面放到最后，并按依赖与规模推进：先公共页、登录、Dashboard，再到系统配置、报表、订单，
最后才是近百个组件的 Campaign 模块。每批变更独立提交，并在进入下一批前运行构建、单测和对应
页面的手工验证。这样出现回归时，排查范围仍然可控。
每个阶段采用的验证目标也不同：基础设施阶段先验证应用能到登录页；替换组件库后验证 Dashboard
和一个 VXE Table 列表；公共组件阶段为每一批组件找一个宿主页面；业务模块阶段再执行相应 E2E 与
完整手工清单。最后才同时要求 lint、单测、生产构建、E2E、兼容警告清理和包体对比。把验证放在
阶段门槛上，比在最后堆一次全量测试更容易定位问题。
验收阶段发现：最棘手的错误往往不在构建期
下面几个问题都没有被“构建成功”捕获，却最能说明为什么迁移需要真实页面和真实交互的回归。
动态组件渲染出 [object Promise]
Vue 2 会把 :is 接收的 () => import('./Component.vue') 当作异步组件工厂；Vue 3 不再隐式做
这个判断。Campaign 详情页按媒体类型切换子组件时，页面没有报错，只是渲染出了
[object Promise]。
修复是显式使用 defineAsyncComponent(() => import('./Component.vue'))。这是一个很好的提醒：
静态检查能发现类型和语法问题，但无法替代“实际点开动态分支”的验证。
Vue Router 4 中 params 与 query 不能凭习惯替换
迁移时若向没有动态路径段的路由传 params，Vue Router 4 会丢弃它并给出警告；而把本应填入必填
动态段的值改放到 query，又会直接抛出 Missing required param，使跳转失败。
最终采用的规则不是“push 用 query、resolve 用 params”，而是只看目标路由的 path：
- 没有声明动态段的值，一律用
query；
- 必填动态段必须用
params；
- 可选动态段两者都可用，但要保持同一路由的读取约定一致。
这条规则后来也指导了可分享 Campaign 链接和内部跳转的收敛，避免了“页面能打开但详情参数丢失”的
静默回归。
这里还有一个值得记录的过程教训：最初的错误启发式是“内部 push() 用 query，构造可分享链接的
resolve() 用 params”。它听起来合理，却忽略了路由定义本身；一次批量替换后，普通列表点击也因
缺少必填 id 而被阻断。修复后，这条规则被单独写入项目记忆。对于 AI 参与的大范围迁移，记录
“曾经为什么改错”与记录最终写法同样重要。
Element Plus 的日期问题会静默污染业务值
Element UI 的日期格式使用 yyyy、dd 等小写 token；Element Plus 基于 dayjs，正确写法是
YYYY、DD。错误 token 不只让输入框显示 Su/02/yyyy 这类乱码，打开面板后会发现实际选中日期
已经错位。
另一个更隐蔽的问题是 default-time="['00:00:00', '23:59:59']"。在 Element Plus 中，裸时间
字符串会被解析为 Invalid Date；当日期范围控件没有绑定值时，内部日期计算继而变成 NaN，日历
面板整体失效。解决方式是使用完整且合法的日期时间字符串，例如
'2000-01-01 00:00:00'。这类差异无法靠 API 名称替换发现，必须在“编辑已有数据”和“新建空数据”
两种场景中分别打开控件核验。
全局性能补丁会破坏组件交互
Campaign 表单中的 vue-multiselect 出现了鼠标点选即关闭、值无法回填的问题，程序化
element.click() 却正常。根因不是组件库或弹窗焦点，而是旧项目引入的
default-passive-events：它把 mousedown 也强制设为 passive，导致组件内部用于保持焦点的
preventDefault() 失效。
修复不是给每个下拉框补事件，而是替换全局补丁，只将 scroll、wheel、touch* 等真正可能阻塞
滚动的事件设为 passive，保留鼠标按键事件的默认行为。迁移过程中遇到“许多地方同时出问题”时，
先检查全局拦截器、样式覆盖和事件补丁，往往比逐页修补更有效。
自动化回归不等于验收：角色和空状态必须进入清单
迁移中的 Playwright 冒烟用例覆盖了登录、Dashboard 和核心列表，但一次后续排查发现，它只使用
管理员账号。管理员的权限路由恰好绕过了非管理员才会经过的 Campaign 详情重定向，因此路由参数的
问题没有在 E2E 中出现，而是在手工以普通角色进入详情时才暴露。
这不是“自动化测试没价值”，而是覆盖模型不完整。对于权限驱动的管理后台，回归清单至少还应包含：
- 一种非管理员角色的登录、菜单生成和深链接访问；
- 有数据与无数据两种表单状态，尤其是日期、默认值和清空操作；
- 列表替换、分页或媒体类型切换后的滚动位置与筛选条件；
- 弹窗、Popover、上传和动态组件等只在后续交互出现的分支；
- 浏览器控制台中的 Vue、路由和组件库警告。
手工 QA 的价值不是重复点一遍自动化脚本，而是专门覆盖权限、真实数据形态和视觉交互这些很难在
一次通用冒烟中穷尽的变量。每个发现都应回流为新的自动化用例、手工检查项，或至少是一条有边界的
迁移规则。
构建产物：不能只看是否超过预算
最终移除 @vue/compat 后，生产包体为 17566.2 kB（未压缩）和 8569.6 kB（gzip），相对基线增长
14.5% 和 15.8%，超过了最初设定的 ±10% 目标。
分析结果表明，这不是一次偶然的打包回归：本次刻意保持 Element Plus 全量引入以控制迁移范围，而
VXE Table 4 的运行时也更重。若要把体积拉回预算，需要单独规划 Element Plus 按需引入和相关验证，
而不是在迁移收尾时混入一次性能优化。把“功能迁移正确”与“下一阶段的优化机会”分开记录，能让交付
结论保持诚实，也不会掩盖后续工作。
这次迁移留下的做法
- 先定义不变项：本次不改业务逻辑、不换状态管理、不换构建器，避免范围膨胀。
- 让兼容层只做临时诊断工具，并把移除它作为验收条件。
- 将可机械化的修改和需要人工判断的修改分开管理，拒绝“一把梭”的全局替换。
- 用登录、列表、表单、详情和弹窗建立真实冒烟基线；构建通过不是功能通过。
- 每一类迁移差异都记录成“现象、根因、修复规则、回归场景”，让后续维护不必重新踩坑。
Vue 2 到 Vue 3 的迁移不是为了把所有组件写成 <script setup>。对一个正在运行的业务系统来说，
更有价值的结果是：应用在原生 Vue 3 运行时上稳定交付，关键交互得到验证，且每一条兼容性债务都有
明确的边界和去向。
]]>
