旧系统从 Vue2 升到 Vue3，往往卡在同一个问题上：业务还在迭代，没人敢停下手上的需求做一次全量切换。一次切的风险不在语法本身，而在于整个应用同时进入不可发布的状态——路由、状态管理、构建工具、第三方组件库都要一起动，出问题时很难定位是哪一层引起的。更稳妥的做法是组件分级迁移：把页面和组件按依赖复杂度分层，用「先边缘、后核心、再框架」的三个阶段逐步替换，让系统在迁移过程中始终保持可发布。
方案一：全量重写或一次性切换
这种做法是把整个前端工程拉到新脚手架里，统一升级构建工具、路由与状态管理，再逐个页面适配。优点是迁移完成后技术栈干净，没有历史包袱，长期维护成本最低。
- 优点：一次到位，不需要维护两套运行环境；重构时可以顺便整理目录结构与废弃代码。
- 代价：迁移期间业务需求基本停滞，回归测试范围覆盖全站；一旦上线后出现兼容问题，回滚成本很高。
- 适用边界：页面数量可控、业务节奏允许冻结一个发布周期，并且有完整的自动化回归用例时，可以考虑。
如果系统承担的是生产核心流程，这种方案通常不建议作为首选。具体能否采用，取决于团队对回归范围的掌控程度。
方案二：组件分级迁移（推荐）
组件分级迁移的思路是：先建立新旧共存的运行基础，再按组件级别逐步替换，页面可以混合使用新旧组件，直到全部迁移完成。它能做到不停业务、按发布节奏推进，也便于把问题定位在单个组件范围内。
阶段一：评估与共存基础。先梳理现有页面、组件、公共依赖与第三方库，按「无状态展示组件 → 有状态业务组件 → 路由与全局状态 → 应用入口」排出优先级。同时搭建新旧代码共存的工程结构，让旧组件能在新应用中运行，或反过来，确保任一层都可独立发布。
阶段二：边缘组件先行。从依赖少、影响面小的展示组件和低频页面开始迁移，验证构建、样式隔离、事件机制与插槽用法。这一阶段的目的是把工具链和适配层磨合好，而不是追求迁移速度。每迁完一批就回归相关页面，问题留在小范围内解决。
阶段三：核心页面与框架层收口。在适配层稳定后，迁移高频业务组件、路由与全局状态，最后处理应用入口和构建配置。收口阶段要把临时的兼容层逐步删除，避免新旧两套写法长期并存。
- 优点：迁移与业务迭代可并行；每次发布的影响面可控，回滚粒度细。
- 代价：过程中要维护共存结构与适配层，对团队规范要求较高；迁移周期取决于组件数量与依赖复杂度，一般不是一两周能完成的。
- 适用边界：业务持续迭代、不能长时间冻结发布的中大型管理系统，通常更适合这条路。
如果需要在现有系统上做同类渐进式改造，可以参考我们的软件定制开发与系统集成服务，其中包含旧系统升级与重构的实施路径。
方案三：微前端渐进替换
微前端是把系统按业务域拆成多个可独立发布的应用，旧应用保持不动，新页面用新框架独立开发，通过统一的容器做路由分发与菜单整合。它在组织层面的收益往往大于技术层面：不同团队可以各自迭代，互不阻塞。
- 优点：新旧应用彻底解耦，迁移可以按业务线分批推进；单个应用出问题不影响整体。
- 代价：需要引入容器、路由分发与公共依赖共享机制，样式隔离和登录态共享要专门设计；运维与发布流程比单体应用复杂。
- 适用边界：系统由多个业务域组成、团队分工明确，且后续仍会长期并行开发时，微前端比较划算。
对于页面规模有限、团队人数不多的系统，引入微前端往往带来额外的复杂度，收益不明显。制造业与物流行业的多系统整合场景里，我们见过把微前端用对也见过用重的情况，判断标准还是业务域是否真的需要独立发布。
什么情况下不要选组件分级迁移
组件分级迁移不是万能解。以下情况建议直接考虑全量重写，或者先做局部重做：
- 应用页面很少、依赖简单，共存结构的搭建成本已经接近直接重写。
- 旧系统本身存在大量无法复用的历史代码，迁移等于重写，分级只会拉长周期。
- 业务即将下线或被新系统替代，投入迁移不划算。
- 团队没有组件规范与回归测试习惯，分级迁移容易变成两套写法长期并存，越迁越乱。
- 对发布时间有硬性窗口、无法接受共存期，这时应评估一次性切换的可行性，而不是硬上分级。
同理，微前端在没有明确业务域边界时不要选——拆出来的应用如果仍然共享大量状态与组件，复杂度只会转移到容器层。
三阶段迁移的执行步骤与验收
- 组件盘点：导出页面与组件清单，标注依赖关系、使用频率与影响范围，作为分级依据。
- 建立共存基础：确认构建工具、依赖版本与适配层方案，保证新旧代码可同时运行、可独立发布。
- 边缘迁移：先迁展示型组件与低频页面，逐个回归，记录适配问题并沉淀为团队规范。
- 核心迁移：迁移高频业务组件、路由与全局状态，同步补充关键路径的回归用例。
- 框架收口：处理应用入口与构建配置，删除临时兼容层，统一代码风格与目录结构。
- 上线验收：按页面清单逐项验收，重点检查样式、事件、路由跳转与权限控制，确认无新旧混用遗留。
需要看具体实施顺序与交付阶段的划分，可以查阅服务范围与交付流程。同类渐进式改造项目可参考同类项目案例，其中包含政企与制造业系统的升级实践。
方案对比速查（文字版）
全量切换 → 适合页面可控、能冻结发布的团队 → 主要代价是迁移期业务停滞与全站回归成本。
组件分级迁移 → 适合业务持续迭代、需要按发布节奏推进的中大型系统 → 主要代价是共存结构与适配层的维护成本。
微前端渐进替换 → 适合多业务域、多团队并行开发的系统 → 主要代价是容器复杂度与运维成本上升。
常见问题
- 迁移期间旧组件还能改需求吗？可以，但建议把改动限制在修复类需求，避免同一组件反复重写。
- 适配层要保留多久？一般到框架收口阶段结束、全量回归通过后即应删除，长期保留会形成第二套技术债。
- 第三方组件库不兼容怎么办？先确认是否有可替换的同类组件，无法替换的做局部封装隔离，不要在全站散落兼容代码。
- 怎么判断可以进入下一阶段？看关键页面回归是否通过、适配问题是否收敛、团队是否已按统一规范开发，而不是看迁移了多少个文件。
