Vue 2 项目接入 Vite 终极指南：@vitejs/plugin-vue2 一文搞定全部配置

【免费下载链接】vite-plugin-vue2Vite plugin for Vue 2.7项目地址: https://gitcode.com/gh_mirrors/vit/vite-plugin-vue2

@vitejs/plugin-vue2 是为 Vue 2.7 量身打造的 Vite 插件，它让老项目也能享受秒级冷启动与热模块替换的现代开发体验。下面这份完整使用教程，从安装配置到避坑技巧，带你一步步把旧项目"提档升级"。

还在为 Vue 2 的慢构建发愁吗？

如果你的团队还在维护 Vue 2 项目，大概率经历过这样的场景：改一行代码，Webpack 冷启动要等十几秒，热更新偶尔还会整页刷新，联调节奏被拖得支离破碎。Vue 2 官方构建链早已停止更新，可业务又不能推倒重来，只能在"凑合用"和"大重构"之间纠结。

其实还有第三条路：把 Vite 搬进 Vue 2 项目。借助 @vitejs/plugin-vue2，老项目无需改动业务代码，就能直接跑在 Vite 的按需编译引擎上。冷启动从十几秒压缩到一秒上下，HMR 精准到单文件级，开发体验几乎追平 Vue 3 新项目。

项目全景速览

@vitejs/plugin-vue2 是一个官方出品的 Vite 插件，专门负责解析.vue单文件组件：把模板编译成渲染函数、把<script>与<script setup>合并编译、把 scoped 样式和 CSS Modules 交给 Vite 管线处理，同时为开发模式注入精细化的 HMR 逻辑。

它和同类方案最大的差异点在于"专一"：只支持 Vue ^2.7.0，不兼容旧版 2.6，因为 2.7 才内置了vue/compiler-sfc。也正是这种专注，让它的编译产物干净利落，与 Vite 3 到 7 全版本兼容。

环境准备与快速上手

准备一个 Node 16+ 环境即可开工。先获取插件源码，方便对照阅读：

git clone https://gitcode.com/gh_mirrors/vit/vite-plugin-vue2

然后在目标 Vue 2 项目里安装插件，注意要确保项目内 Vue 版本不低于 2.7：

npm install @vitejs/plugin-vue2 vue@^2.7.0

接着在项目根目录创建vite.config.js，这行配置解决了"Vite 如何识别 Vue 组件"这一核心问题：

import { createVuePlugin } from '@vitejs/plugin-vue2' export default { plugins: [createVuePlugin()] }

最后启动开发服务器验证效果：

npm run dev

看到 Vite 输出启动地址、浏览器能正常渲染页面，就说明插件已经接管了 Vue 组件的编译工作。此时随便改一个组件的模板或样式，你会发现浏览器几乎是"秒改秒刷新"，这就是它带来的第一份见面礼。

实战场景拆解

场景一：让 Vue 2 组件用上<script setup>新语法

需求背景：Vue 2.7 虽然兼容 Composition API，但<script setup>这套更简洁的写法需要编译器支持，原生 Webpack 链路往往配不齐。

解决方案：插件在编译阶段会调用vue/compiler-sfc的compileScript，把<script setup>与普通<script>合并成一份标准脚本。源码中的transformMain函数就是负责这一合并逻辑的核心枢纽，见 核心编译入口。

关键代码：新建一个ScriptSetup.vue，你可以在 playground/ScriptSetup.vue 看到完整示例，核心长这样：

<script setup lang="ts"> import { ref } from 'vue' defineProps<{ msg: string }>() const count = ref(0) </script> <template> <div> <span>{{ msg }}</span> <button @click="count++">{{ count }}</button> </div> </template>

效果说明：类型推导、自动暴露模板变量全部开箱即用，TypeScript 用户可以直接享受defineProps泛型带来的类型检查，写组件就像在 Vue 3 项目里一样顺手。

场景二：scoped 样式与 CSS Modules 的正确打开方式

需求背景：老项目里样式隔离靠scoped，新代码想引入 CSS Modules，两种写法混用是常态，插件必须都能扛住。

解决方案：插件为每个组件生成唯一的scopeId，编译时把scoped选择器注入到模板和样式两侧；遇到<style module>则会转成 CSS Modules 导入并挂载到$style上。对应实现可以翻看 样式处理模块 与 组件编译总流程 中的genStyleCode函数。

关键代码：一个组件内同时混用两种样式方案，参考 playground/css/TestCssModules.vue：

<template> <div> <div class="scoped-box">这段只受 scoped 影响</div> <div :class="$style.blue">这段走 CSS Modules</div> </div> </template> <style scoped> .scoped-box { color: rebeccapurple; } </style> <style module> .blue { color: blue; } </style>

效果说明：scoped 样式不会污染全局，CSS Modules 的类名经过 hash 处理不会撞名，两种隔离策略在一份文件里和平共处，样式问题从此不再是噩梦。

场景三：模板里的静态资源路径自动变成 ESM 导入

需求背景：Vue 2 时代图片、字体等资源要么手写 require，要么挂到 public 目录，路径管理十分繁琐。

解决方案：插件编译模板时会把img、video、source等标签的静态资源属性自动改写为 ES 模块导入，再交给 Vite 的资源管线处理，源码实现见 src/template.ts 和 src/compiler.ts。完整案例可参考 playground/test-assets/TestAssets.vue。

关键代码，以下模板写法：

<template> <img src="./nested/logo.png" /> </template>

等价于编译后的：

<script> import _imports_0 from './nested/logo.png' </script> <template> <img :src="_imports_0" /> </template>

效果说明：小图片自动内联、大图片自动加 hash 指纹，你只管写相对路径，打包优化的事交给 Vite。唯一要注意的是，只有静态字符串路径才会被转换，动态路径仍需手动import。

进阶技巧与最佳实践

用 include/exclude 圈定编译范围

大型仓库里混着第三方.vue文件时，可以通过过滤规则让插件只处理自己关心的文件，减少无谓编译：

createVuePlugin({ include: [/\.vue$/, /src\/components/], exclude: /node_modules/ })

自定义 SFC 块，给组件塞私有数据

想在组件里直接写 i18n 文案或文档信息？插件会把<custom>等自定义块单独导出，配合一个小插件即可注入到组件选项里，见 自定义块示例：

const vueI18nPlugin = { name: 'vue-i18n', transform(code, id) { if (!/vue&type=i18n/.test(id)) return return `export default Comp => { Comp.i18n = ${code} }` } }

透传 compilerOptions 微调编译细节

需要关闭模板表达式校验、自定义指令插值或修改预处理配置时，直接透传即可：

createVuePlugin({ template: { compilerOptions: { whitespace: 'condense' } } })

避坑指南

报错：Failed to resolve vue/compiler-sfc

原因：项目里 Vue 版本低于 2.7，或没有安装 vue。resolveCompiler会先从项目根目录查找编译器，找不到就抛错，相关逻辑见 src/compiler.ts。 解法：执行npm install vue@^2.7.0，确保项目依赖树里存在 Vue 2.7+。

报错：vue 未定义或渲染异常

原因：开发模式下插件会强制把vue别名指向vue.runtime.esm.js，如果你在代码里用了 Vue 全量构建才有的模板字符串编译（如Vue.extend({ template: '...' })），运行时版本不支持。 解法：改用 render 函数或 SFC 模板；确实需要运行时编译时，在 vite 配置中手动调整vue别名。

HMR 偶尔整页刷新

原因：handleHotUpdate中对比新旧 descriptor 后发现 script 或 custom block 发生了变化，只能降级为 reload；这属于正常行为，并非插件缺陷。判断逻辑可看 src/handleHotUpdate.ts 的isOnlyTemplateChanged。 解法：把频繁变动的内容尽量收敛到模板与样式块中，改模板时就能命中"仅重渲染"的快速通道。

注意：README 中特别标注，Vue 2 已进入 EOL，本项目随之停止积极维护。生产环境仍可使用，但请做好长期维护预案。

高频问答（FAQ）

Q：这个插件支持 Vue 2.6 吗？A：不支持。插件从 2.7 才有的vue/compiler-sfc获取编译能力，2.6 及以下必须配合vue-template-compiler的另一套链路，无法混用。

Q：装完插件后 build 报错怎么办？A：先确认 Vite 版本在 3.0~7.0 范围内，再检查 Vue 是否为 2.7+。插件对 Vite 的 peer 依赖覆盖很广，版本错配是绝大多数报错的根源。

Q：生产构建和开发模式有区别吗？A：有。开发模式会注入 HMR 运行时和__file信息便于 DevTools 定位，生产模式则全部裁剪，且会自动禁用 devtools，产物更干净，见 src/main.ts 中的devToolsEnabled判断。

Q：可以在 Nuxt 或老式 webpack 项目里用它吗？A：不行，它只能作为 Vite 插件工作。如果要迁移老项目，建议先抽离业务组件，逐个验证兼容性后再整体切换。

Q：第三方 Vue 2 生态库能正常用吗？A：绝大多数可以。插件只处理.vue文件的编译与 HMR，不影响依赖预构建。遇到个别库在 Vite 下报错，多半是它内部依赖了 webpack 特有 API，可参考 测试用例 排查思路。

总结与延伸

@vitejs/plugin-vue2 用极低的迁移成本，把 Vue 2 项目的开发体验拉到了现代标准：秒级冷启动、精准 HMR、原生<script setup>、自动资源处理，每一项都直击老项目的痛点。虽然 Vue 2 已进入维护尾声，但只要你还在维护这类项目，它就是性价比最高的一次升级。

想深入了解实现细节，可以继续阅读 插件入口与选项定义、热更新引擎 以及 编译流水线；玩转各类场景的完整示例都集中在 playground 目录，从 scoped 样式到自定义块一应俱全。配置不复杂、上手不痛苦，改一行配置，就能让老项目重新"跑起来"。

【免费下载链接】vite-plugin-vue2Vite plugin for Vue 2.7项目地址: https://gitcode.com/gh_mirrors/vit/vite-plugin-vue2