用 Vite 创建 Vue 3 项目：从零搭建到迁移踩坑全攻略

说实话，我最早接触 Vue 3 的时候还习惯用 vue-cli 那一套，vue create project完了之后等几十秒，起来一个项目慢慢跑。后来被同事按着头试了一次 Vite，五六秒内开发服务器就绪、保存代码立刻热更新，这个体感差别实在太大了。到今天，Vite 几乎已经成了 Vue 3 项目默认的启动方式，不管是官方文档还是企业新项目，清一色npm create vue@latest。

这篇内容就是围绕"用 Vite 创建 Vue 3 项目"这条主线，把我实际创建项目、配环境、踩坑、从 Vue 2 迁到 Vue 3 的经验完整拆一遍。不管你是刚接触 Vue 3 的新人，还是正在把老项目升级到 Vue 3 的开发者，按照下面的步骤走，基本不会出大问题。我会把为什么这么做、底层是什么原理、遇到报错怎么排查也一并写清楚，不会只给一堆命令让你直接抄。

1. 为什么 Vite 几乎成了 Vue 3 的默认选择

1.1 Vite 与 Vue CLI：同样是构建工具，设计思路完全不同

Vue CLI 用的底层还是 webpack，开发服务器启动时要把整个应用从头到尾打包一遍，项目越大，启动越慢。你改一行代码，webpack 也要重新编译受影响的模块，早期版本甚至要等好几秒才能看到更新。Vite 的做法完全不同，它直接利用浏览器原生 ES Module 能力，开发阶段不需要把源代码打包成 bundle，而是让浏览器按需请求模块文件，服务器只负责把对应的文件内容返回即可。

这个思路听起来玄乎，打个比方就明白了。webpack 相当于一个图书馆管理员，你说要看某本书，他要先把整个图书馆的书全部重新整理摆放一遍再递给你。Vite 则只在你伸手的时候，从书架上抽出你要的那一本。你翻下一页，他才去拿下一页的书。所以项目规模再大，Vite 的冷启动速度也基本维持在一秒到两秒之间，因为启动时它根本不处理你的业务代码，只启动了一个静态文件服务加上模块依赖预构建。

开发体验的差距只是第一步，构建环节 Vite 也有优势。生产构建时 Vite 默认使用 Rollup，Rollup 对 ES Module 的 tree-shaking 处理非常彻底，打包产物干净。当然 webpack 也能做 tree-shaking，但配置成本高、容易踩坑，Vite 在这方面几乎是开箱即得。对 Vue 3 项目来说，Vite 从开发到构建的整体链路非常顺滑，这也是 Vue 官方把 Vite 列为推荐工具的原因。

1.2 用 Vite 搭 Vue3 项目，能省下哪些心

抛开启动速度，Vite 对 Vue 3 的支持还有一个隐藏优势：插件和配置可以直接复用生态里的成套方案。比如@vitejs/plugin-vue负责把单文件组件编译成 JS，@vitejs/plugin-vue-jsx支持在.tsx/.jsx文件里写 Vue 组件，@vitejs/plugin-vue-devtools则可以帮忙调试 Vue 组件状态。这些插件在 vue-cli 时代也有对应的 webpack loader，但 loader 的版本兼容问题特别多，遇到 Vue 3 + TypeScript + JSX + Sass 的组合，webpack 配置会让你怀疑人生。

Vite 的配置本身也是一个加分项。vite.config.ts文件里的配置项足够直观，resolve alias、server 端口、proxy 代理、build 分包这些高频操作写起来非常简洁。对新手来说，Vite 的报错信息也比 webpack 友好得多，模块解析失败、依赖加载错误这类问题，Vite 基本能直接告诉你是什么文件、哪一行、缺什么依赖。

如果你再去对比 Next.js 和 Vite，会发现两者定位完全不同。Next.js 是一个全栈 React 框架，自带路由、SSR、服务端数据获取能力。Vite 则是纯粹的构建工具，它不做 SSR 方案，不内置路由，也不限定 UI 框架。Vue 3 项目里，Vite 扮演的角色就是"快速搭建 + 高效编译 + 灵活配置"，页面渲染、状态管理、路由这些工作全部交给 Vue 生态自己完成。两者没有谁取代谁的关系，选型时看你需要的是框架级能力还是构建工具级能力。

2. 实操：从零创建一个 Vite + Vue 3 项目

2.1 先把环境准备好：Node 版本、包管理器

创建 Vite 项目之前，先确认你机器上的 Node 版本。Vite 5 要求 Node 18 以上，Vite 6 则要求 Node 18+ 或者 20+，Vite 7 开始要求 Node 20.19+ 或 22.12+。如果 Node 版本太旧，npm create vue可能直接报错，或者安装依赖时出现引擎不兼容警告。我建议至少用 Node 20 LTS，这个版本稳定、生态兼容性好，各种工具链基本都能跑起来。

检查方法很简单，终端输入：

node -v npm -v

如果版本偏低，别犹豫，直接去 Node 官网下载 LTS 版本，或者用 nvm 切版本。nvm 管理 Node 版本有一个好处，不同项目可以单独指定 Node 版本，避免一个全局环境带不动所有项目。前端项目最怕的就是"在我电脑上能跑"，Node 版本不一致是这种问题的头号原因。

包管理器方面，npm、pnpm、yarn 都可以。我个人推荐 pnpm，它的依赖安装速度和磁盘占用比 npm 好不少，monorepo 场景下更是首选。不过如果你团队统一用 npm，那也没什么问题。Vite 官方脚手架对这三种包管理器都做了支持，命令略有差异：

# npm npm create vue@latest # pnpm pnpm create vue@latest # yarn yarn create vue@latest

实际执行时会让你选择项目名称和一系列特性，比如是否集成 TypeScript、JSX、Vue Router、Pinia、ESLint、Prettier。我建议第一次创建项目时把 TypeScript 和 Vue Router 勾上，Pinia 也可以勾，后面基本都会用到，省得自己再加。

2.2 用官方脚手架 create-vue 初始化项目

以 npm 为例，创建项目的完整流程如下：

npm create vue@latest my-vue3-app

终端里会出现交互式选项，按需选择即可。下面是我个人比较常用的组合：

✓ 使用 TypeScript? Yes ✓ 使用 JSX? No ✓ 使用 Vue Router? Yes ✓ 使用 Pinia? Yes ✓ 使用 Vitest? No ✓ 使用 ESLint? Yes ✓ 使用 Prettier? Yes

项目创建完成之后，进入目录并安装依赖：

cd my-vue3-app npm install npm run dev

默认情况下 Vite 会启动http://localhost:5173，浏览器打开就能看到 Vue 3 的欢迎页面。如果你希望开发服务器自动打开浏览器，可以修改package.json里的 dev 脚本：

"dev": "vite --open"

创建出来的项目结构非常清晰，核心目录如下：

├── src │ ├── assets │ ├── components │ ├── router │ ├── stores │ ├── views │ ├── App.vue │ └── main.ts ├── index.html ├── package.json ├── tsconfig.json ├── vite.config.ts └── env.d.ts

这里重点提一下index.html的位置，它是 Vite 项目的入口文件，直接放在根目录。开发时 Vite 会解析这个文件里的<script type="module" src="/src/main.ts">，生产构建时也会以它作为 HTML 模板。这和 Vue CLI 那个public/index.html的路径不一样，迁移老项目时别搞混。

2.3 手工搭建一个最小 Vite + Vue 3 工程

有时候你不需要脚手架生成的一大堆文件，只想快速起一个小项目，或者想彻底搞清楚 Vite 和 Vue 3 怎么组合的，那手工搭建也是一种很好的理解方式。整个过程其实只需要四个文件。

项目目录结构：

manual-vite-vue/ ├── package.json ├── index.html ├── vite.config.js └── src ├── main.js └── App.vue

package.json：

{ "name": "manual-vite-vue", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }, "dependencies": { "vue": "^3.5.0" }, "devDependencies": { "@vitejs/plugin-vue": "^5.0.0", "vite": "^6.0.0" } }

vite.config.js：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()] })

index.html：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Vite + Vue 3</title> </head> <body> <div id="app"></div> <script type="module" src="/src/main.js"></script> </body> </html>

src/main.js：

import { createApp } from 'vue' import App from './App.vue' createApp(App).mount('#app')

src/App.vue：

<script setup> import { ref } from 'vue' const count = ref(0) </script> <template> <div> <h1>Vite + Vue 3</h1> <button @click="count++">count is {{ count }}</button> </div> </template>

然后执行：

npm install npm run dev

一个最精简的 Vite + Vue 3 项目就跑起来了。手工搭的好处是你能把每个文件的作用看清楚，脚手架生成的项目固然省事，但很多新人连src/main.ts里的createApp(App).mount('#app')是干嘛的都没搞明白。自己搭一遍之后再去用脚手架，心里就有底了。

3. 常用配置与进阶接入

3.1 接入 TypeScript、JSX、Sass

如果你是新建项目，脚手架已经在 Vite 配置里帮你接好了 TypeScript。但如果是在手工项目里加 TS，只需要在vite.config.ts里配置：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': '/src' } } })

同时安装typescript、vue-tsc，并在package.json的 build 脚本里加上类型检查：

"build": "vue-tsc -b && vite build"

这里解释一下为什么要单独加vue-tsc。Vite 的构建管道本身不会检查 TypeScript 类型错误，它只是把.ts文件里的类型信息剥离掉，再把代码转成 JS。如果项目里类型错误一堆，Vite 照样能构建成功。加了vue-tsc之后，构建前会先做一次完整的类型检查，让类型错误在 CI 阶段就被拦截下来。很多老项目升级 Vue 3 后"编译过了但跑起来报错"，一部分原因就是没做类型检查，把隐患留到了运行时。

Sass 的接入也非常简单。安装sass（注意不是node-sass，那个项目已经停止维护了）：

npm install -D sass

安装完成后不需要在 Vite 配置文件里写任何东西，因为在<style lang="scss">里使用 scss 语法时，Vite 会自动调用sass编译器。如果你想配置全局的 scss 变量、mixin，可以在vite.config.ts里加：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], css: { preprocessorOptions: { scss: { additionalData: `@import "@/styles/variables.scss";` } } } })

这样每个组件的 scss 都会自动注入全局变量文件，不需要在每个组件里手动 import。需要注意，这个配置会注入到所有 scss 代码块，如果variables.scss太大，会稍微增加每个组件的编译时间，但是换来的是全局变量随处可用，性价比很高。

JSX 的接入走@vitejs/plugin-vue-jsx：

npm install -D @vitejs/plugin-vue-jsx

然后在vite.config.ts里：

import vueJsx from '@vitejs/plugin-vue-jsx' export default defineConfig({ plugins: [vue(), vueJsx()] })

之后你就能在.tsx文件里写 Vue 组件的 JSX 语法了。Vue 3 里用 JSX 和模板选择哪个？我个人的实践是：模板优先，JSX 用于动态渲染逻辑非常复杂的场景。比如要根据配置数据递归渲染一系列组件、或者在一个函数里返回多个根节点的组件，JSX 明显更直白。普通列表、表单、页面结构，用模板的可读性更高。

3.2 接入路由、状态管理、Mock 搭建

路由和状态管理我就不讲基础用法了，重点说拿到一个新项目时怎么选版本。Vue 3 对应的是 Vue Router 4 和 Pinia，千万别再装 Vue Router 3 或者 Vuex 4（现在其实也支持 Vue 3，但新项目还是优先 Pinia）。

创建好项目后，如果你用的是脚手架的npm run dev，启动的端口是 5173。但开发时前后端分离，通常需要代理。Vite 的代理配置在vite.config.ts的server.proxy字段：

export default defineConfig({ server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } })

changeOrigin: true很关键，它会把代理请求的Host头改成目标服务器的地址，否则部分后端在鉴权或者跨域校验时会拒绝请求。rewrite则是在转发时把/api前缀去掉，因为很多后端的接口路径里并没有/api这个层级。

Mock 方案上，Vite 生态里有vite-plugin-mock，但我在真实项目里更推荐另一种思路：直接用 Node 写一个简单的 mock server，启动时用concurrently同时跑 Vite 和 mock 服务。或者更轻量的方式，在 Vite 的configureServer钩子里注册几条中间件路由，直接返回 mock 数据。这种方式完全不依赖额外插件，适合小项目。

3.3 局域网访问、端口和浏览器打开

开发机想用手机或者局域网内另一台电脑访问项目，默认配置是不行的，Vite 默认只绑定localhost。解决办法是在vite.config.ts里配置：

export default defineConfig({ server: { host: true, port: 5173 } })

host: true表示监听所有网卡地址，启动后终端会显示Network: http://192.168.x.x:5173，局域网内的设备只要和开发机在同一网段，就能直接访问这个地址。

“局域网打开空白”这个问题很多人遇到过。页面能打开，但内容空白，浏览器控制台报Failed to fetch dynamically imported module，或者Uncaught SyntaxError。根本原因通常是浏览器版本太老，不支持原生 ES Module。Vite 开发模式下所有模块都是按 ESM 方式加载的，IE 和旧版 Edge 根本玩不了，新版浏览器基本都没问题。排查思路先确认浏览器版本，再按 F12 看控制台具体报错。

另外，在 Linux 环境下跑vite命令时，如果遇到类似xdg-open的报错，是因为 Vite 尝试调用系统默认浏览器打开页面，但系统没有安装xdg-open，或者 Wayland 环境下没有注册默认浏览器。解决办法是启动时不要自动开浏览器，手动复制终端提示的地址去访问。

4. 踩坑实录：从 Vue 2 迁移到 Vue 3

4.1 API 层面的差异和常见误改

把成熟项目从 Vue 2 迁到 Vue 3，很多人以为切换依赖版本就行，实际上 API 层面的改动会触及每个组件。首先明确一点：Vue 2 的选项式 API 在 Vue 3 里依然能用，但 Vue 3 全新的组合式 API 才是主流。如果项目体量大、团队没精力逐个组件重写，短期方案是保留选项式语法，只改框架核心，长期再看情况逐步迁移。

最容易踩的坑是原来的Vue.prototype.$xxx。Vue 2 里给原型挂全局属性很方便，Vue 3 则必须用app.config.globalProperties.$xxx，而且这个属性只在组件实例上通过this.$xxx访问，组合式 API 里this不存在，你需要在setup里通过getCurrentInstance().appContext.config.globalProperties去拿，或者干脆用 Provide/Inject 方案。

生命周期函数也需要逐一对上。Vue 2 的created和beforeDestroy在 Vue 3 组合式 API 中分别是onBeforeMount或者直接在 setup 里写逻辑、onBeforeUnmount。mounted、updated、watch这些在 setup 里都有对应的钩子函数，但千万注意beforeDestroy这种写法是上一代 API，Vue 3 里不会报错，但也不推荐，切换到onBeforeUnmount更标准。

组件通信的改动也很大。Vue 2 的$on、$off方法在 Vue 3 里被移除了，如果你之前直接用全局事件总线做跨组件通信，迁移时会发现到处是乱报错。Vue 3 官方推荐方案是mitt这个库，只有两百多行代码，API 和 EventEmitter 类似，替换成本很低。更规范的做法是用 Pinia 管理共享状态，事件总线的问题（组件销毁后监听还残留、事件名容易写错）Pinia 都能避免。

4.2 第三方库依赖 Node 内建模块导致的报错

迁移到 Vite 之后，有一个高频错误：Module "buffer" has been externalized for browser compatibility，或者process is not defined。这个问题的根源不是 Vite 本身，而是很多第三方库是从 Node 生态移植过来的，内部依赖了buffer、process、stream这类 Node 内置模块。浏览器里没有这些全局对象，Vite 在开发时会给出警告，但项目一旦用到这个库，运行时报错就跑不掉了。

我遇到过最典型的是xlsx-style这类表格处理库，它内部依赖buffer。网上很多文章让你在vite.config.ts里加resolve.alias把buffer指向buffer/的浏览器 polyfill，再配置define全局变量，实际效果有时还是不稳定。我个人的处理思路分三步：

第一步，先看这个库有没有浏览器版本或者 ESM 版本。比如 SheetJS 官方维护的xlsx是纯 JS 库，不需要 polyfill，直接用就行。如果非要用xlsx-style，那就要接受它对构建工具的不友好。

第二步，尽量选择纯 ESM 且自带浏览器兼容声明的库。Vite 生态经过几年发展，主流库基本都已经兼容浏览器环境，很少有“非用不可”的老库不能替换。

第三步，如果实在绕不过去，才手动配置 polyfill。参考做法是安装buffer、process这类包，然后在vite.config.ts的define字段里声明process.env的默认值，再在resolve.alias里做映射。这样能解决一部分库的报错，但你要清楚这只是“带病运行”，后续可能还有其他模块缺失问题。

4.3 表格、表单、导入导出等业务场景注意事项

Vue 3 项目最常见的业务类型就是后台管理系统，而管理系统里最绕不开的表格和表单。表格组件从 Vue 2 迁移到 Vue 3，容易出问题的点在于渲染机制变化。比如某些老表格库依赖 Vue 2 的数组响应式劫持方式，Vue 3 改用 Proxy 之后，部分表格的列配置、单元格渲染函数可能不再生效，表现是数据变了但表格不刷新。解决方向有两个：要么升级到表格库支持 Vue 3 的新版本（比如 vxe-table 4.x），要么把表格的数据变更写成响应式对象赋值，而不是直接改嵌套属性。

用了 vxe-table 这类重型表格后，很多人会反馈“首屏加载变慢”。本质原因是表格组件体积大，如果全部打包进主 chunk，一次加载所有代码，首屏必然慢。解决办法是路由懒加载 + 组件按需引入，vxe-table 本身支持按需注册，只引入使用的表格、列、分页组件，不要一股脑全量引入。另外再配合 Vite 的build.rollupOptions手动分包，把体积大的第三方依赖单独切成一个 chunk，利用浏览器并行加载可以缩小首屏阻断时间。

表单方面，Vue 3 的v-model行为比 Vue 2 更严格，动态添加和删除表单一行的需求在 Vue 3 里有几种常见写坏方式。如果你用 index 作为v-for的 key，删除中间一行时，后面所有行都会重新渲染，输入框的内容可能串行。正确的做法是给每行生成一个唯一 id，比如crypto.randomUUID()或者自增 counter。另外在表单校验里，动态行的 rules 经常遇到“校验不触发”或者“删除行后校验状态残留”的问题，解决方案是删除行时同步清理该行的校验状态，用formRef拿到实例后调用clearValidate，再对剩余字段重新触发校验。

5. 高频问题排查速查

5.1 开发环境页面白屏

Vite 项目页面白屏，最常见的几种原因我给你整理成了一张排查表：

这里重点说 last 情况。history 路由模式在正式部署到 Nginx 时，也必须配置try_files $uri $uri/ /index.html，否则刷新页面就是 404。Vite 开发服务器默认已经支持了 SPA fallback，所以你在开发环境感觉不到这个问题，部署后才暴露。

5.2 首屏优化与构建体积控制

新项目搭起来之后的第一版上线，往往会出现首屏资源加载过大的问题。Vite 生产构建默认会做代码压缩，但第三方库的代码依然体积可观。以一个包含 Element Plus、echarts、axios、vue-router、pinia 的后台管理系统为例，如果全部打进一个 chunk，一个 JS 文件可能超过 1MB，首屏加载时间在低端网络环境下直接奔着 5 秒去。

优化思路第一是把 echarts 这类体积很大的库按需引入，只注册用到的图表类型。Element Plus 组件库也支持按需引入，用unplugin-vue-components自动导入组件和样式，可以省掉一大部分体积。第二是手动分包，vite.config.ts里配置：

build: { rollupOptions: { output: { manualChunks: { vendor: ['vue', 'vue-router', 'pinia'], ui: ['element-plus'], charts: ['echarts'] } } } }

这样做的好处是浏览器能利用 HTTP 缓存：升级业务代码时，vendor 和 ui 的 chunk 内容不变，缓存依然有效，用户只需要下载新业务代码，而不是重新下载包含全部依赖的主文件。

第三点是路由懒加载，这个几乎成了 Vue 项目的标配。Vue Router 4 里直接写动态 import：

const Home = () => import('../views/HomeView.vue')

页面级别的组件全部改成这种写法，首屏只加载当前页面需要的组件代码。我在实际项目里观察到的收益非常明显：后台管理系统首屏 JS 体积从 2MB 降到了 800KB 左右，转换时间快了一半以上。

5.3 浏览器兼容性相关的疑难杂症

Vue 3 项目在浏览器兼容性上的问题，往往不是框架本身不兼容，而是构建产物和浏览器能力之间的错配。如果项目需要支持旧版 Edge 或者某些国产浏览器内置的旧内核，你需要使用@vitejs/plugin-legacy，它会帮你把 ES Module 代码转换成 ES5 版本，同时生成 legacy chunk。但这里我要提醒一句：Vite 本身的核心构建能力依赖现代浏览器，启用 legacy 插件之后，构建复杂度会上升、产物体积会增加，如果目标用户群用的是近三年内的浏览器版本，这个问题其实不需要过度担心，直接放弃旧内核浏览器是更合理的产品决策。

还有一个让我排查很久的问题：同一个 Vue 3 项目在 Chrome 里完全正常，在 Edge 里偶尔出现页面卡死、操作按钮点了没反应。后来发现是某个组件库的样式和 Edge 的渲染机制产生了兼容问题，把组件的 CSS 用了display: contents的高频场景改掉就好了。这类问题没有通用结论，排查思路是先缩小范围：停用扩展、切换浏览器内核、注释掉可疑组件，用二分法定位到具体组件再处理。更实用的一点是给项目配置良心的降级方案，比如关键功能加异常兜底提示，而不是让用户直接看到白屏。

最后再分享一个我自己常用的习惯：新项目建好之后，第一件事不是写业务代码，而是跑一次npm run build确认生产构建没问题，再配置好 lint 和格式化。这能在项目起步阶段就把环境问题、类型错误、构建异常全部暴露出来，等业务代码积累到几万行再回头处理这些基础问题，成本完全是数量级上的差异。Vite 和 Vue 3 的组合本身已经很成熟，很多坑其实都出在项目基础没有夯实，先把底子打好，后面写业务代码会顺很多。