28.2 迁移工具：Vue Migration Helper 使用

从 Vue 2 升级到 Vue 3，很多时候工作量不在“重写业务逻辑”，而是在“适配那些被移除或变更的 API”。一个中型项目可能有数百个组件，纯靠人工检查 v-model 语法是否过时、生命周期钩子是否改名，既耗时又容易遗漏。

Vue 官方提供了 Vue Migration Helper（具体实现为 vue-codemod 工具集和 CLI），它的作用是自动扫描你的源代码，找出不兼容 Vue 3 的写法，并给出可选的自动修复。

安装

Migration Helper 以 npm 包的形式发布，推荐在项目根目录下全局或本地安装：

npm install -g vue-codemod

或者直接在项目中本地安装：

npm install --save-dev vue-codemod

基本用法

安装完成后，通过 npx 调用 CLI，指定要扫描的文件夹路径：

npx vue-codemod <path> [options]

常用参数：

--transforms：指定要执行的转换规则（如 vue-async-component、remove-vue-use）。
--no-interactive：禁用交互式询问，直接执行所有转换。
--apply：直接修复文件，否则默认只打印分析结果而不修改。

最常用的命令——扫描整个 src 目录并在交互模式下选择要修复的规则：

npx vue-codemod ./src

它能检测和修复哪些问题

Migration Helper 内置了一套规则集，专门针对 Vue 2 → Vue 3 的破坏性变更。主要类别包括：

1. 模板语法变更

v-model 的 .sync 修饰符移除：Vue 3 中统一为 v-model:propName。
v-if 与 v-for 优先级调整：Vue 3 中 v-if 优先级高于 v-for，与 Vue 2 相反。
key 属性在 <template v-for> 上的位置：Vue 3 要求 key 写在 <template> 上而非子节点。

2. 生命周期钩子重命名

beforeDestroy → beforeUnmount
destroyed → unmounted

3. 全局 API 变更

Vue.prototype → app.config.globalProperties
Vue.component、Vue.directive → app.component、app.directive
Vue.mixin、Vue.use 等用法发生变化

4. 过滤器（Filters）移除
Vue 3 不再支持模板中的过滤器语法（{{ message | capitalize }}），需要改为计算属性或方法。工具会指出使用了过滤器的位置，但无法自动转换为方法调用。

5. 事件总线（EventBus）移除
Vue 3 移除了 $on、$off、$once 实例方法，Migration Helper 会标记出这些调用并建议替换方案。

6. 渲染函数 API 变更
h 函数现在需要从 vue 中全局导入，不再作为渲染上下文参数传入。

实际操作示例

假设你的 Vue 2 项目中有这样一个组件：

<template>
  <div>
    <span>销毁前执行清理</span>
  </div>
</template>

<script>
export default {
  beforeDestroy() {
    console.log('清理中...')
  }
}
</script>

运行 npx vue-codemod ./src 后，工具会识别出 beforeDestroy 已废弃，提示：

? The hook `beforeDestroy` has been renamed to `beforeUnmount`. 
  Apply fix? (Y/n)

选择 Y 后，代码会被自动修改为：

<script>
export default {
  beforeUnmount() {
    console.log('清理中...')
  }
}
</script>

对于无法完全自动修复的情况（如过滤器），工具会生成带注释的警告，并建议手动调整方案。

配合 @vue/compat 使用

Migration Helper 适合在迁移初期批量处理语法变更，但它不能覆盖 100% 的运行时行为差异。更稳妥的路径是：

安装 @vue/compat 构建产物，让项目在 Vue 3 中运行时兼容大部分 Vue 2 的旧语法。
用 Migration Helper 扫描并修复可自动转换的部分。
运行项目，关注控制台中的废弃警告，逐一修复那些工具未能处理的行为差异。
最终移除 @vue/compat，切换到纯 Vue 3 模式。

注意事项与局限性

不能替代测试：工具的自动修复通常只涉及 API 的命名替换，不保证业务逻辑在 Vue 3 下表现一致（例如依赖了 Vue 2 内部异常处理方式）。
复杂场景需人工介入：如果代码中动态生成选项对象、使用高阶组件或 Mixin 定义生命周期钩子，静态分析可能漏检。
先备份或提交：建议在干净的工作区运行，并用 Git 跟踪变化，方便回撤。
版本更新：vue-codemod 本身也在迭代，运行前最好更新到最新版本（npm update -g vue-codemod）。

整体而言，Vue Migration Helper 是一个省时利器，能把批量、重复的 API 替换工作自动化，让开发者把精力集中在真正的逻辑验证和业务迁移上。它是 28.1 节所述的“破坏性变更总览”的具体落地工具，也是迈向完全迁移的关键一步。