Vue2 项目迁移至 Vite 实战:解决兼容性与 SVG 图标配置

作者:雾松时间:2026-10-31 12:22:43浏览:619

本文详解如何将 Vue2 项目迁移至 Vite 构建工具。通过安装 vite-plugin-vue2 解决版本兼容问题,修正挂载方式与模板编译器缺失错误,并重新配置开发服务器代理以解决跨域。此外,还介绍了 vite-plugin-svg-icons 的使用及 SvgIcon 组件的全局注册方法,帮助开发者平滑过渡并优化开发体验。

背景

Vite 是伴随 Vue3 推出的构建工具,显著提升了开发效率。其核心优势在于省略了开发环境下的打包步骤,直接将 ES 模块源码传输给浏览器,利用浏览器原生的 <script module> 功能进行解析支持。

然而,Vite 主要面向 Vue3 生态设计。对于仍在使用 Vue2 的老项目,直接迁移至 Vite 需要解决兼容性问题,具体操作路径如下。

过程

首先,通过 vite 命令创建一个新的 Vue 项目。

npm init @vitejs/app

在初始化过程中,选择 Vue 模板(Vite 同时也支持 React、Vanilla、Svelte、Preact 等其他框架模板)。

接着,将老项目中依赖的 npm 包安装到新项目中。

特别注意:必须同时安装老项目所使用的 Vue2 版本,例如本文示例中使用的 vue2.5.2 版本。

背景

将老项目的 src 目录文件复制到新生成的 Vite 项目中,并尝试运行。

此时运行通常会报错,原因是 vite.config.js 中默认配置的插件仅支持 Vue3 及以上版本,因此需要引入支持 Vue2 的专用插件。

背景

安装支持 Vue2 的插件,并相应修改 vite.config.js 配置文件。

npm install vite-plugin-vue2 -D

背景

再次运行项目后,可能会遇到新的报错(有报错说明仍有修复空间,若无报错反而可能意味着配置遗漏)。

根据报错信息定位问题,提示找不到 vue-template-compiler 模块,此时需手动安装该模块即可解决。

背景

npm install vue-template-compiler -D

安装完成后再次运行,页面可能仍未渲染,打开控制台查看发现新的错误。

错误原因通常是无法找到 #app 挂载点。Vue2 中传统的 DOM 元素挂载方式在 Vite 环境中未生效,因此需要修改 main.js 中根元素的挂载逻辑。

背景

背景

项目运行后,若发现接口请求报错(如出现跨域错误或 404),这是因为 Vue CLI 的代理配置与 Vite 的代理机制存在差异,需按照 Vite 规范重新配置代理。

server: {
		port: 8081, // 自己本地需要运行的端口
		fs: { // 不对根目录访问做限制
			strict: false,
		},
		proxy: {
			'/Index': { // 不要写成根路径!!!否则会直接跳转到线上地址
				target: 'http://www.需要代理的地址/',
				changeOrigin: true,
				rewrite: (path) => path.replace(/^\//, '') // 不要写成rewrite: (path) => path.replace(/^\/Index/, '')!!!否则会报404
			},
			'/Home': { // 不要写成根路径!!!否则会直接跳转到线上地址
				target: 'http://www.需要代理的地址/',
				changeOrigin: true,
				rewrite: (path) => path.replace(/^\//, '')
			},
		}
	},

完成上述调整后再次运行,项目即可成功启动。

========= vite 增加svg插件使用 =========

vite中使用svg图

1.安装插件

npm i vite-plugin-svg-icons -D

2.配置vite.config.js文件, 并在src下新建文件夹icons,放入要使用的 .svg图片,如下:

// 引入
import viteSvgIcons from 'vite-plugin-svg-icons'

// 插件配置
plugins: [
	viteSvgIcons({
		iconDirs: [path.resolve(process.cwd(), 'src/icons')], // 在src下新建文件夹icons
		symbolId: 'icon-[dir]-[name]'
	})
],

背景

注意:

如果使用 import viteSvgIcons from 'vite-plugin-svg-icons’报错,则需要换成这种写法

import { createSvgIconsPlugin } from ‘vite-plugin-svg-icons'
 createSvgIconsPlugin({
     iconDirs: [path.resolve(process.cwd(), 'src/icons')], // 在src下新建文件夹icons
     symbolId: 'icon-[dir]-[name]'
   })

3. components下新建SvgIcon.vue文件,增加内容

<template>
	<svg aria-hidden="true">
		<use :href="symbolId" rel="external nofollow"  rel="external nofollow"  :fill="color" />
	</svg>
</template>

<script>
	export default {
		name: 'SvgIcon',
		props: {
			prefix: {
				type: String,
				default: 'icon',
			},
			name: {
				type: String,
				required: true,
			},
			color: {
				type: String,
				default: '#333',
			},
		},
		data() {
			return {
				symbolId: ''
			}
		},
		mounted() {
			this.symbolId = `#${this.prefix}-${this.name}`
		},
	}
</script>

<style scoped>
	svg { // 根据开发需求设置css
		width: 20px;
		height: 20px;
	}
</style>

注意⚠️:vue3中SvgIcon组件代码这么写

<template>
  <svg aria-hidden="true" class="svg-icon" :width="props.size" :height="props.size">
    <use :xlink:href="symbolId" rel="external nofollow"  rel="external nofollow"   :fill="props.color" />
  </svg>
</template>
 
<script setup>
import { computed } from 'vue'
const props = defineProps({
  prefix: {
    type: String,
    default: 'icon'
  },
  name: {
    type: String,
    required: true
  },
  color: {
    type: String,
    default: '#ffffff'
  },
  size: {
    type: String,
    default: '1rem'
  }
})
const symbolId = computed(() => `#${props.prefix}-${props.name}`)
</script>

<style scoped>
svg {
  width: 16px;
  height: 16px;
}
</style>

4.main.js中引入

import 'virtual:svg-icons-register'

5.全局注册svg

// main.ts中引入

import SvgIcon from './components/SvgIcon.vue'

createApp(App)
.use(router)
.component('svg-icon', SvgIcon)
.mount('#app')

6.组件中使用svg

背景

template使用

背景

效果图,正常显示。

背景

如果要修改svg颜色,修改icons下 如account.svg中的fill字段为currentColor

背景

页面中设置样式的color即可

背景

总结

以上为个人经验,希望能给大家一个参考,也希望大家多多支持本站。

作者最新文章