Vue 2 到 Vue 3 迁移策略

// main.js - Vue 2
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'

// 全局配置
Vue.config.productionTip = false
Vue.prototype.$http = myHttpLib

// 全局组件
Vue.component('MyButton', MyButton)

// 全局指令
Vue.directive('focus', {
  inserted: el => el.focus()
})

// 全局过滤器
Vue.filter('capitalize', value => {
  if (!value) return ''
  return value.charAt(0).toUpperCase() + value.slice(1)
})

new Vue({
  router,
  store,
  render: h => h(App)
}).$mount('#app')

// main.js - Vue 3
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { createPinia } from 'pinia'

const app = createApp(App)

// 使用插件
app.use(router)
app.use(createPinia())

// 全局配置
app.config.errorHandler = (err) => {
  console.error(err)
}

// 全局属性（替代 Vue.prototype）
app.config.globalProperties.$http = myHttpLib

// 全局组件
app.component('MyButton', MyButton)

// 全局指令
app.directive('focus', {
  mounted: el => el.focus() // 钩子名称改变
})

// ❌ Vue 3 移除了过滤器
// 使用计算属性或方法替代

app.mount('#app')

// Vue 2
export default {
  beforeDestroy() {
    console.log('组件即将销毁')
  },
  destroyed() {
    console.log('组件已销毁')
  }
}

// Vue 3
export default {
  beforeUnmount() {
    console.log('组件即将卸载')
  },
  unmounted() {
    console.log('组件已卸载')
  }
}

// Vue 2 指令钩子
Vue.directive('focus', {
  bind(el, binding, vnode) {
    // 指令首次绑定到元素时
  },
  inserted(el, binding, vnode) {
    // 元素插入父节点时
    el.focus()
  },
  update(el, binding, vnode, oldVnode) {
    // VNode 更新时
  },
  componentUpdated(el, binding, vnode, oldVnode) {
    // VNode 及其子 VNode 全部更新后
  },
  unbind(el, binding, vnode) {
    // 指令与元素解绑时
  }
})

// Vue 3 指令钩子（命名更统一）
app.directive('focus', {
  created(el, binding, vnode, prevVnode) {
    // 新增：元素创建后、属性绑定前
  },
  beforeMount(el, binding, vnode, prevVnode) {
    // 新增：元素挂载前
  },
  mounted(el, binding, vnode, prevVnode) {
    // 替代 inserted
    el.focus()
  },
  beforeUpdate(el, binding, vnode, prevVnode) {
    // 新增：元素更新前
  },
  updated(el, binding, vnode, prevVnode) {
    // 替代 componentUpdated
  },
  beforeUnmount(el, binding, vnode, prevVnode) {
    // 新增：元素卸载前
  },
  unmounted(el, binding, vnode, prevVnode) {
    // 替代 unbind
  }
})

<!-- Vue 2: v-model 默认使用 value prop 和 input 事件 -->
<CustomInput v-model="value" />

<!-- 等价于 -->
<CustomInput :value="value" @input="value = $event" />

<!-- Vue 2: 多个 v-model 使用 .sync -->
<CustomInput :value.sync="value" :title.sync="title" />

<!-- 子组件 Vue 2 -->
<template>
  <input :value="value" @input="$emit('input', $event.target.value)" />
</template>

<script>
export default {
  props: ['value']
}
</script>

<!-- Vue 3: v-model 默认使用 modelValue prop 和 update:modelValue 事件 -->
<CustomInput v-model="value" />

<!-- 等价于 -->
<CustomInput 
  :modelValue="value" 
  @update:modelValue="value = $event" 
/>

<!-- Vue 3: 多个 v-model 更简洁 -->
<CustomInput v-model:value="value" v-model:title="title" />

<!-- 子组件 Vue 3 -->
<template>
  <input 
    :value="modelValue" 
    @input="$emit('update:modelValue', $event.target.value)" 
  />
</template>

<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue']
}
</script>

// ❌ Vue 2 写法 - Vue 3 已移除
<template>
  <div>{{ message | capitalize }}</div>
</template>

<script>
export default {
  filters: {
    capitalize(value) {
      return value.charAt(0).toUpperCase() + value.slice(1)
    }
  }
}
</script>

// ✅ Vue 3 替代方案 1: 计算属性
<template>
  <div>{{ capitalizedMessage }}</div>
</template>

<script>
export default {
  computed: {
    capitalizedMessage() {
      return this.message.charAt(0).toUpperCase() + this.message.slice(1)
    }
  }
}
</script>

// ✅ Vue 3 替代方案 2: 方法
<template>
  <div>{{ capitalize(message) }}</div>
</template>

<script>
export default {
  methods: {
    capitalize(value) {
      return value.charAt(0).toUpperCase() + value.slice(1)
    }
  }
}
</script>

// ❌ Vue 2 写法 - Vue 3 已移除
this.$on('event', handler)
this.$off('event', handler)
this.$once('event', handler)

// ✅ Vue 3 替代方案：使用外部库 mitt 或 tiny-emitter
import mitt from 'mitt'
const emitter = mitt()

emitter.on('event', handler)
emitter.off('event', handler)
emitter.emit('event', payload)

<!-- ❌ Vue 2 写法 - Vue 3 已移除 -->
<MyComponent inline-template>
  <div>
    <p>这些内容将被视为组件模板</p>
  </div>
</MyComponent>

<!-- ✅ Vue 3 替代方案：使用插槽 -->
<MyComponent>
  <template #default>
    <div>
      <p>这些内容将被视为插槽内容</p>
    </div>
  </template>
</MyComponent>

// Vue 2 响应式限制
export default {
  data() {
    return {
      user: { name: 'Alice' },
      items: [1, 2, 3]
    }
  },
  methods: {
    // ❌ Vue 2 无法检测新属性添加
    addProperty() {
      this.user.age = 25 // 非响应式
    },
    
    // ❌ Vue 2 无法检测属性删除
    removeProperty() {
      delete this.user.name // 非响应式
    },
    
    // ❌ Vue 2 无法检测数组索引赋值
    updateItem() {
      this.items[0] = 10 // 非响应式
    },
    
    // ✅ Vue 2 正确写法
    addPropertyCorrect() {
      this.$set(this.user, 'age', 25) // 或 Vue.set
    },
    
    updateItemCorrect() {
      this.$set(this.items, 0, 10) // 或 Vue.set
    }
  }
}

// Vue 3 响应式优势（基于 Proxy）
export default {
  data() {
    return {
      user: { name: 'Alice' },
      items: [1, 2, 3]
    }
  },
  methods: {
    // ✅ Vue 3 可以检测新属性添加
    addProperty() {
      this.user.age = 25 // 响应式
    },
    
    // ✅ Vue 3 可以检测属性删除
    removeProperty() {
      delete this.user.name // 响应式
    },
    
    // ✅ Vue 3 可以检测数组索引赋值
    updateItem() {
      this.items[0] = 10 // 响应式
    }
  }
}

<!-- Vue 2 函数式组件 -->
<template functional>
  <div>{{ props.message }}</div>
</template>

<script>
export default {
  props: ['message']
}
</script>

<!-- Vue 3：函数式组件只能以纯函数形式创建 -->
<!-- （functional 选项与 <template functional> 写法已移除） -->
<script>
import { h } from 'vue'

export default function FunctionalMessage(props, context) {
  return h('div', props.message)
}

FunctionalMessage.props = ['message']
</script>

<!-- Vue 2：v-for 优先级高于 v-if，可以在同一元素上用 v-for 的变量做条件 -->
<li v-for="user in users" v-if="user.active" :key="user.id">{{ user.name }}</li>

<!-- Vue 3：v-if 优先级更高，v-if 无法访问 v-for 作用域内的变量，上例会报错 -->
<!-- ✅ Vue 3 正确写法：外层 template 包一层 v-for -->
<template v-for="user in users" :key="user.id">
  <li v-if="user.active">{{ user.name }}</li>
</template>

<!-- 或在 computed 中先过滤 -->

<!-- Vue 2：<template v-for> 的 key 要放在子元素上 -->
<template v-for="item in list">
  <div :key="item.id">{{ item.name }}</div>
</template>

<!-- Vue 3：key 应放在 template 上 -->
<template v-for="item in list" :key="item.id">
  <div>{{ item.name }}</div>
</template>

<!-- 另外：v-if/v-else 分支在 Vue 3 中不再需要手动添加 key -->
<!-- Vue 3 会为分支自动生成唯一 key -->

/* Vue 2 */
.v-enter,
.v-leave-to {
  opacity: 0;
}

/* Vue 3：v-enter → v-enter-from，v-leave → v-leave-from */
/* v-enter-active / v-enter-to / v-leave-active / v-leave-to 不变 */
.v-enter-from,
.v-leave-to {
  opacity: 0;
}

// Vue 2
const AsyncComponent = () => import('./AsyncComponent.vue')

// 或带配置
const AsyncComponent = () => ({
  component: import('./AsyncComponent.vue'),
  loading: LoadingComponent,
  error: ErrorComponent,
  delay: 200,
  timeout: 3000
})

// Vue 3
import { defineAsyncComponent } from 'vue'

const AsyncComponent = defineAsyncComponent(() => 
  import('./AsyncComponent.vue')
)

// 或带配置
const AsyncComponent = defineAsyncComponent({
  loader: () => import('./AsyncComponent.vue'),
  loadingComponent: LoadingComponent,
  errorComponent: ErrorComponent,
  delay: 200,
  timeout: 3000
})

# 安装 Vue 3 和兼容性构建
npm install vue@3 @vue/compat@3

# 安装迁移构建工具
npm install -D @vue/compiler-sfc@3

// vue.config.js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  chainWebpack: config => {
    config.resolve.alias.set('vue', '@vue/compat')
    
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        return {
          ...options,
          compilerOptions: {
            compatConfig: {
              MODE: 2
            }
          }
        }
      })
  }
})

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: {
            MODE: 2
          }
        }
      }
    })
  ],
  resolve: {
    alias: {
      vue: '@vue/compat'
    }
  }
})

// main.js
import { createApp, configureCompat } from 'vue'
import App from './App.vue'

// 全局配置兼容性行为
configureCompat({
  // MODE: 2 启用 Vue 2 行为
  MODE: 2,
  
  // 可针对特定特性配置
  // 'OPTIONS_BEFORE_CREATE': false, // 禁用某个兼容行为
  
  // 全局配置
  GLOBAL_MOUNT: false,
  GLOBAL_EXTEND: false
})

const app = createApp(App)
app.mount('#app')

// 运行时会输出警告
[Vue warn]: (deprecation ATTR_FALSE_VALUE) 
Attribute "disabled" with v-bind value 'false' will render 
disabled="" instead of removing it in Vue 3. 
For detailed usage, check: https://v3-migration.vuejs.org/breaking-changes/attribute-coercion.html

# 官方没有一键评估工具，常用做法是静态搜索 + 运行时警告：

# 1) 全局搜索已移除/更名的 API 用法
grep -rn "Vue\.filter\|Vue\.directive\|Vue\.component\|\$on(\|\$off(\|\$once(\|beforeDestroy\|destroyed\|inline-template" src/

# 2) 升级到 @vue/compat 迁移构建后运行项目，统计控制台输出的弃用警告
npm run serve

# 控制台输出示例
# [Vue warn]: (deprecation FILTERS) ...
# [Vue warn]: (deprecation ATTR_FALSE_VALUE) ...

# 检查依赖兼容性
npm outdated

# 查看 Vue 3 兼容的替代库
# Vue Router 3 -> Vue Router 4
# Vuex 3 -> Vuex 4 或 Pinia
# Element UI -> Element Plus
# Vuetify 2 -> Vuetify 3

# 创建迁移分支
git checkout -b vue3-migration

# 备份当前版本
git tag vue2-backup

// 步骤 1: 更新 main.js
// Vue 2
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'

Vue.config.productionTip = false
new Vue({
  router,
  store,
  render: h => h(App)
}).$mount('#app')

// Vue 3
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { createPinia } from 'pinia'

const app = createApp(App)
app.use(router)
app.use(createPinia())
app.mount('#app')

// Vue Router 3
import VueRouter from 'vue-router'
Vue.use(VueRouter)

const router = new VueRouter({
  routes: [...]
})

// Vue Router 4
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
})

// 路由守卫变更
// Vue Router 3
router.beforeEach((to, from, next) => {
  next()
})

// Vue Router 4
router.beforeEach((to, from) => {
  // return false 取消导航
  // return '/redirect' 重定向
  // 不返回或返回 true 继续导航
})

// Vuex 3
import Vuex from 'vuex'
Vue.use(Vuex)

const store = new Vuex.Store({
  state: { count: 0 },
  mutations: {
    increment(state) {
      state.count++
    }
  }
})

// Vuex 4
import { createStore } from 'vuex'

const store = createStore({
  state: { count: 0 },
  mutations: {
    increment(state) {
      state.count++
    }
  }
})

// Pinia (推荐)
import { createPinia, defineStore } from 'pinia'

const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++
    }
  }
})

// 在组件中使用
const counter = useCounterStore()
counter.increment()

[ ] 更新自定义指令钩子名称
[ ] 移除过滤器，使用计算属性或方法替代
[ ] 更新 v-model 绑定（value -> modelValue）
[ ] 更新生命周期钩子（beforeDestroy -> beforeUnmount）
[ ] 检查函数式组件写法
[ ] 更新异步组件导入方式
[ ] 移除 $on/$off/$once，使用外部事件库
[ ] 检查并修复响应式限制问题

// 步骤 1: 启用迁移构建
// package.json
{
  "dependencies": {
    "vue": "^3.1.0",
    "@vue/compat": "^3.1.0"
  }
}

// 步骤 2: 运行项目，查看警告
npm run serve

// 步骤 3: 逐个修复警告
// 例如修复过滤器
// ❌
<div>{{ message | capitalize }}</div>

// ✅
<div>{{ capitalize(message) }}</div>

// 步骤 4: 修复完所有警告后，移除 @vue/compat
npm uninstall @vue/compat

// Vue Test Utils v1 (Vue 2)
import { mount } from '@vue/test-utils'
import Component from './Component.vue'

test('renders correctly', () => {
  const wrapper = mount(Component)
  expect(wrapper.text()).toContain('Hello')
})

// Vue Test Utils v2 (Vue 3)
import { mount } from '@vue/test-utils'
import Component from './Component.vue'

test('renders correctly', () => {
  const wrapper = mount(Component)
  expect(wrapper.text()).toContain('Hello')
})

// 主要变更：一些 API 方法名变化
// wrapper.vm.$emit() -> wrapper.vm.$emit() (相同)
// wrapper.find() -> 仍支持
// wrapper.findAll() -> 返回数组而非对象

// Cypress 测试示例
describe('Vue 3 Migration', () => {
  it('should render app correctly', () => {
    cy.visit('/')
    cy.get('.app').should('exist')
  })
  
  it('should handle user interactions', () => {
    cy.get('button').click()
    cy.get('.count').should('contain', '1')
  })
})

// 使用 Chrome DevTools Performance 进行对比
// 或使用 lighthouse
npx lighthouse http://localhost:8080 --view

// 记录关键指标
// - First Contentful Paint (FCP)
// - Largest Contentful Paint (LCP)
// - Total Blocking Time (TBT)

# 11-Nginx基础概述 配置示例
upstream vue2_backend {
  server 127.0.0.1:8080;
}

upstream vue3_backend {
  server 127.0.0.1:8081;
}

server {
  listen 80;
  server_name example.com;
  
  # 10% 流量到 Vue 3 版本
  split_clients "${remote_addr}" $backend {
    10%    vue3_backend;
    *      vue2_backend;
  }
  
  location / {
    proxy_pass http://$backend;
  }
}

// 添加错误监控
app.config.errorHandler = (err, vm, info) => {
  // 发送到错误监控系统
  trackError({
    message: err.message,
    stack: err.stack,
    info,
    vueVersion: 3
  })
}

// 准备回滚方案
// 1. 保留 Vue 2 版本代码
// 2. 准备快速回滚脚本
// 3. 监控关键业务指标

# Vue 2 打包示意
dist/js/app.123abc.js  150kb

# Vue 3 打包示意
dist/js/app.456def.js   90kb  # 减少约 40%（示意）

# 安装 Element Plus
npm install element-plus

# main.js
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

app.use(ElementPlus, { locale: zhCn })

// Vue 2 + TypeScript
import { Vue, Component } from 'vue-property-decorator'

@Component({
  props: {
    title: String
  }
})
export default class MyComponent extends Vue {
  title!: string
  count = 0
  
  increment() {
    this.count++
  }
}

// Vue 3 + TypeScript (更简洁)
<script setup lang="ts">
interface Props {
  title: string
}

const props = defineProps<Props>()
const count = ref(0)

function increment() {
  count.value++
}
</script>

// 临时方案：使用兼容层
import { createApp } from 'vue'
import LegacyPlugin from 'legacy-vue2-plugin'

// 包装为 Vue 3 插件
const compatPlugin = {
  install(app) {
    // 模拟 Vue 2 API
    app.config.globalProperties.$legacy = LegacyPlugin
  }
}

app.use(compatPlugin)

main (Vue 2)
  └── vue3-migration (Vue 3 迁移)
        ├── feature/update-router
        ├── feature/update-store
        └── fix/component-issues

# 迁移进度跟踪

## 已完成
- [x] 全局 API 迁移
- [x] 路由升级到 Vue Router 4

## 进行中
- [ ] Vuex 迁移到 Pinia

## 待开始
- [ ] 组件库升级

// 1. 模块化迁移
// 将项目拆分为独立模块
const modules = {
  'user-center': Vue 3,
  'order-system': Vue 2.7,  // 保持
  'product-catalog': Vue 3
}

// 2. 微前端方案
// 使用 qiankun 或 single-spa
import { registerMicroApps, start } from 'qiankun'

registerMicroApps([
  {
    name: 'vue2-app',
    entry: '//localhost:8081',
    container: '#vue2-container',
    activeRule: '/vue2'
  },
  {
    name: 'vue3-app',
    entry: '//localhost:8082',
    container: '#vue3-container',
    activeRule: '/vue3'
  }
])

start()

// 1. 单元测试覆盖率检查
npm run test:unit -- --coverage

// 2. E2E 测试覆盖核心流程
describe('核心业务流程', () => {
  it('用户登录', () => { /* ... */ })
  it('下单流程', () => { /* ... */ })
  it('支付流程', () => { /* ... */ })
})

// 3. 视觉回归测试
// 使用 Percy、BackstopJS 等工具

[ ] 评估项目规模和复杂度
[ ] 检查所有依赖的 Vue 3 兼容性
[ ] 确认团队时间和资源充足
[ ] 创建完整的测试用例
[ ] 备份当前代码
[ ] 制定详细的迁移计划

[ ] 更新 main.js 入口文件
[ ] 迁移路由到 Vue Router 4
[ ] 迁移状态管理（Vuex 4 或 Pinia）
[ ] 更新自定义指令
[ ] 移除过滤器
[ ] 更新 v-model 绑定
[ ] 更新生命周期钩子名称
[ ] 检查函数式组件
[ ] 更新异步组件写法
[ ] 替换 $on/$off/$once
[ ] 检查响应式代码
[ ] 更新单元测试

[ ] 所有单元测试通过
[ ] E2E 测试通过
[ ] 性能指标符合预期
[ ] 浏览器兼容性测试
[ ] 移动端测试（如适用）
[ ] 错误监控正常
[ ] 生产环境灰度测试
[ ] 文档更新完成