从Vue2到Vue3：ant-design-vue-pro项目迁移完全指南-优快云博客

从Vue2到Vue3：ant-design-vue-pro项目迁移完全指南

【免费下载链接】ant-design-vue-pro 项目地址: https://gitcode.com/gh_mirrors/antd/ant-design-vue-pro

你是否正面临Vue2项目性能瓶颈？是否想体验Vue3的Composition API和更好的TypeScript支持？本文将带你一步步完成ant-design-vue-pro从Vue2到Vue3的迁移，解决兼容性问题，优化项目架构。读完本文，你将掌握核心依赖升级、代码适配、组件改造和构建配置优化的全流程。

项目现状分析

当前项目基于Vue2构建，主要依赖版本信息如下：

Vue 版本：2.6.14
ant-design-vue 版本：1.7.8
Vue Router 版本：3.5.3
Vuex 版本：3.6.2

项目构建配置位于 vue.config.js，入口文件为 src/main.js。项目使用了Vue CLI 5进行构建，采用了Less预处理器和ESLint代码检查。

迁移准备工作

环境要求

迁移前请确保本地环境满足以下要求：

Node.js 14.0.0 或更高版本
npm 6.0.0+ 或 yarn 1.22.0+
Git 版本控制工具

迁移工具安装

首先安装Vue官方提供的迁移工具：

npm install -g @vue/compiler-sfc @vue/cli@next
npm install @vue/compiler-sfc --save-dev

项目备份

在开始迁移前，建议创建一个新的分支进行迁移工作：

git checkout -b migrate-to-vue3

核心依赖升级

package.json 改造

首先需要更新项目的核心依赖，修改 package.json 文件：

{
  "dependencies": {
    "vue": "^3.2.47",
    "vue-router": "^4.1.6",
    "vuex": "^4.1.0",
    "vue-i18n": "^9.2.2",
    "ant-design-vue": "^3.2.15",
    "@ant-design-vue/pro-layout": "^3.0.0"
  },
  "devDependencies": {
    "@vue/cli-plugin-babel": "~5.0.8",
    "@vue/cli-plugin-eslint": "~5.0.8",
    "@vue/cli-service": "~5.0.8",
    "@vue/compiler-sfc": "^3.2.47",
    "vue-loader": "^17.0.1"
  }
}

然后安装更新后的依赖：

rm -rf node_modules package-lock.json
npm install

构建配置调整

Vue CLI 配置更新

修改 vue.config.js，更新webpack配置以适应Vue3：

// 添加Vue3的相关配置
module.exports = {
  chainWebpack: config => {
    // Vue3不再需要vue-template-compiler
    config.resolve.alias.delete('vue$')
    config.resolve.alias.set('vue$', 'vue/dist/vue.esm-bundler.js')
    
    // 更新svg loader配置
    config.module
      .rule('svg')
      .use('vue-svg-loader')
      .loader('vue-svg-loader')
      .options({
        // Vue3不需要transformAssetUrls
        svgo: {
          plugins: [
            { prefixIds: true },
            { cleanupIDs: true }
          ]
        }
      })
  }
}

Babel 配置更新

创建或修改 babel.config.js：

module.exports = {
  presets: [
    '@vue/cli-plugin-babel/preset'
  ],
  plugins: [
    [
      "import",
      { libraryName: "ant-design-vue", libraryDirectory: "es", style: true }
    ]
  ]
}

代码适配与重构

入口文件改造

修改 src/main.js，适配Vue3的新语法：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
import i18n from './locales'
import { VueAxios } from './utils/request'
import ProLayout from '@ant-design-vue/pro-layout'
import themePluginConfig from '../config/themePluginConfig'

import bootstrap from './core/bootstrap'
import './core/lazy_use'
import './permission'
import './utils/filter'
import './global.less'

const app = createApp(App)

// 全局注册组件
app.component('pro-layout', ProLayout)

// 挂载常用API
app.use(router)
app.use(store)
app.use(i18n)
app.use(VueAxios)

// 初始化
bootstrap(app)

app.mount('#app')

Vue Router 4 迁移

创建新的路由配置文件 src/router/index.js：

import { createRouter, createWebHashHistory } from 'vue-router'
import { constantRouterMap, asyncRouterMap } from './config/router.config'

const router = createRouter({
  history: createWebHashHistory(),
  routes: constantRouterMap
})

export default router

Vuex 4 迁移

修改 src/store/index.js：

import { createStore } from 'vuex'
import app from './modules/app'
import user from './modules/user'

export default createStore({
  modules: {
    app,
    user
  },
  getters: {
    token: state => state.user.token,
    avatar: state => state.user.avatar,
    name: state => state.user.name,
    roles: state => state.user.roles
  }
})

组件改造示例

以 src/views/dashboard/Analysis.vue 为例，将Vue2组件转换为Vue3组件：

<template>
  <page-container :title="$t('dashboard.analysis.title')">
    <a-row :gutter="16">
      <!-- 内容区域 -->
      <a-col :span="12">
        <chart-card title="销售额趋势">
          <mini-area :data="salesData" />
        </chart-card>
      </a-col>
    </a-row>
  </page-container>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { useI18n } from 'vue-i18n'
import ChartCard from '@/components/Charts/ChartCard.vue'
import MiniArea from '@/components/Charts/MiniArea.vue'
import { fetchSalesData } from '@/api/dashboard'

const { t } = useI18n()
const salesData = ref([])

onMounted(async () => {
  const res = await fetchSalesData()
  salesData.value = res.data
})
</script>

样式适配

主题配置更新

修改主题配置文件 config/themePluginConfig.js：

module.exports = {
  theme: {
    'primary-color': '#1890ff',
    'link-color': '#1890ff',
    'success-color': '#52c41a',
    'warning-color': '#faad14',
    'error-color': '#f5222d',
    'layout-header-height': '64px',
    'border-radius-base': '2px'
  },
  // 其他配置...
}

测试与验证

本地开发环境测试

启动开发服务器，验证基本功能是否正常：

npm run serve

构建测试

执行构建命令，检查是否能正常打包：

npm run build

自动化测试

如果项目有单元测试，需要更新测试配置 jest.config.js 以支持Vue3：

module.exports = {
  preset: '@vue/cli-plugin-unit-jest',
  transform: {
    '^.+\\.vue$': 'vue-jest'
  },
  moduleFileExtensions: ['vue', 'js', 'json', 'jsx', 'ts', 'tsx', 'node']
}

常见问题解决方案

Composition API 迁移

对于复杂组件，建议使用Composition API重构，例如创建 src/views/form/basicForm/index.vue 的组合式API版本：

<template>
  <a-form :model="formState" @finish="handleSubmit">
    <!-- 表单内容 -->
  </a-form>
</template>

<script setup>
import { ref, reactive } from 'vue'

const formState = reactive({
  name: '',
  email: ''
})

const handleSubmit = (values) => {
  console.log('Success:', values)
}
</script>

兼容性问题处理

问题描述	解决方案
`$attrs` 包含 `class` 和 `style`	使用 `inheritAttrs: false` 并手动绑定
`$listeners` 被移除	统一使用 `$attrs`
过滤器 (Filters) 被移除	使用方法调用或计算属性替代
`v-model` 语法变化	改为 `v-model:value` 或使用 `.sync` 修饰符

迁移总结与后续优化

迁移 checklist

核心依赖已升级到Vue3兼容版本
构建配置已更新
路由和状态管理已迁移
组件代码已适配Vue3语法
样式和主题正常工作
所有测试用例通过

性能优化建议

使用 <script setup> 语法减少模板代码
采用Tree-Shaking减小包体积
使用Composition API拆分复杂逻辑
合理使用Teleport组件优化DOM结构
利用Vue3的响应式系统优化重渲染性能

结语

通过本文介绍的步骤，你已经完成了ant-design-vue-pro项目从Vue2到Vue3的迁移。Vue3的Composition API、更好的TypeScript支持和性能优化将为你的项目带来长期收益。迁移过程中遇到的问题，大部分可以在Vue官方文档或ant-design-vue的迁移指南中找到解决方案。

迁移是一个持续优化的过程，建议逐步进行，先保证核心功能正常运行，再逐步应用Vue3的新特性进行优化。祝你迁移顺利！

【免费下载链接】ant-design-vue-pro 项目地址: https://gitcode.com/gh_mirrors/antd/ant-design-vue-pro

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考