简介面向初学者的Vue3与Vite项目创建指南以傻瓜式步骤讲解从环境准备到项目部署的完整流程无需深厚基础即可上手适合刚接触前端工程化、希望快速搭建项目的开发者。内容涵盖开发工具安装、项目初始化、本地服务器启动、组合式应用封装复用、路由配置以及生产环境打包部署等关键环节每个步骤都配有可直接运行的命令与代码片段例如编写自定义组合式函数、封装可复用逻辑、配置多页面路由等方便读者边看边练、对照实现。资源包共690个文件以JavaScript、TypeScript、JSON、Markdown、Map等类型为主包含项目源码、类型声明、配置文件、依赖映射及说明文档并附有Vue Router、Pinia等常用模块文件。压缩包大小10.83MB内部目录按源码、公共组件、组合式函数、路由与状态管理等模块划分结构清晰便于按需检索和对照学习。目前已有2791人学习教程贴合实际开发场景按步骤操作即可完成项目从零到一的搭建同时理解组合式编程的代码组织方式与现代化构建工具的核心优势为后续深入开发打下扎实基础。 写这篇教程的起因很简单我经常看到很多初学者在群里问“vue3项目到底怎么创建”然后就被网上一堆复杂的教程劝退了。说实话用 vue3 vite 创建项目这件事本身真的没有那么复杂打开终端敲几行命令就能搞定难的是你不知道为什么这样做以及踩坑之后不知道怎么排查。我用这套流程带过不少新人也帮不少人解决过创建、启动、打包阶段的报错。这篇文章不搞那些花里胡哨的东西就从零开始把 vue3 vite 创建项目这条链路讲明白每一步该干什么、为什么这么干、遇到问题怎么查全部捋清楚。不管你是刚入门的前端新人还是后端同学想写点前端页面这套傻瓜式教程都可以帮你稳稳地把项目跑起来。1. 环境准备与版本选择1.1 Node.js 版本是第一个坑vue3 vite 的项目本质上是运行在 Node.js 环境上的所以第一步不是装什么编辑器而是确认电脑里的 Node.js 版本够不够新。Vite 4 要求 Node.js 14.18 / 16Vite 5 要求 18Vite 6 则明确要求 18.0.0 或 20.0.0 以上的版本。如果你还在用 Node 12 或者更老的版本执行创建命令的时候大概率会直接报错报错信息类似npm error engine node12.0.0 is incompatible。检查版本的方法很简单打开终端Windows 用 cmd 或 PowerShellmacOS 用 Terminal输入node -v npm -v我推荐直接把 Node.js 装到最新的 LTS 版本目前 20.x 是最稳妥的选择。官网nodejs.org下载安装包一路下一步就行。装完之后记得重新开一个终端窗口让环境变量生效。注意不要装那种“预览版”“Current”版本虽然功能新但有些依赖可能还没跟上回归起来很麻烦。干活就用 LTS准没错。1.2 包管理器npm 还是 pnpm创建 vue3 vite 项目时你一定会遇到“用什么包管理器安装依赖”的问题。默认大家都会用 npm因为它是 Node.js 自带的零成本。但如果你稍微折腾过几个项目就会发现npm 安装依赖有时候会特别慢还会产生一些依赖层级过深的问题。所以我更推荐 pnpm它的特点是速度快、节省磁盘空间最重要的是它把依赖做成了硬链接多个项目共用一份缓存安装效率比 npm 高很多。npm install -g pnpm装完以后后面所有命令都可以把npm替换成pnpm比如pnpm install、pnpm dev、pnpm build。如果你暂时不想用 pnpm继续用 npm 也完全没问题流程是一样的。1.3 编辑器选择老实说VSCode 最省心很多后端同学习惯用 IDEA 或者 Eclipse会问我能不能直接在 IDEA 里创建 vue3 项目。我的建议是前端项目还是单独用 VSCode 或 WebStorm 打开比较舒服。原因很简单Vue 生态的插件、调试工具、代码提示几乎都是围绕 VSCode 做的。在 IDEA 里强行写 Vue 也不是不行但你会遇到插件不全、提示缺失、格式化风格冲突等一系列问题。我自己实测下来的感受是前端代码就用 VSCode 写后端代码用 IDEA两扇窗各管各的协作最顺畅。2. 三步创建你的第一个 Vue3 项目2.1 使用 create-vue 脚手架创建vue3 vite 的官方脚手架叫create-vue它是 Vue 官方维护的和vue-cli是两套东西注意不要混淆。创建项目只需要一条命令npm create vuelatest执行这条命令后命令行会进入交互式问答模式让你填写项目名称、选择需要安装的功能。接下来你只需要按照自己的需求回答几个问题。2.2 交互选项逐项说明很多新手看到问号就慌了不知道该选什么。我把常见的问题列一下每个选项都解释清楚选什么、为什么Project name项目名称输入你想要的项目目录名比如vue3-demo。注意这里不要用大写字母不要用中文最好用横杠连接多个单词。Add TypeScript?是否添加 TypeScript我建议选 Yes。虽然 TS 刚接触会有点不习惯但现在的 vue3 项目里 TS 已经是默认趋势了包括组件 props、ref 泛型类型提示能帮你少写很多低级 bug。Add JSX Support?如果你没有用 JSX 写 Vue 组件的需求可以先选 No。Vue 的主推写法是模板语法template项目默认不需要 JSX。Add Vue Router?如果你的项目有多个页面、需要跳转就选 Yes。单页面或组件展示类的 demo 可以选 No后面手动加也不难。Add Pinia?Pinia 是 vue3 时代的状态管理库如果你需要跨组件共享数据比如用户登录状态、购物车数据就选 Yes。如果只是做练习选 No 也影响不大。Add Vitest?这是单元测试框架初学者可以先选 No不用在测试上花太多时间。Add ESLint and Prettier?建议选 Yes。ESLint 负责检查代码规范Prettier 负责格式化代码虽然刚上手会感觉“怎么这么多报错”但养成习惯之后收益非常大。选完之后脚手架就会在当前目录下生成一个完整的 vue3 vite 项目骨架。2.3 启动与目录结构项目生成后进入目录安装依赖启动开发服务器cd vue3-demo npm install npm run dev默认情况下终端会输出Local: http://localhost:5173/浏览器打开这个地址看到 Vue 官方的欢迎页面就说明项目创建成功了。这时候你会看到生成的项目里有一个src目录里面主要是main.js入口文件、App.vue根组件、components/组件目录、router/路由配置如果你选了的话。vite 的项目结构其实很直观一段时间后你就发现所有页面代码基本都写在src下面而项目根目录的vite.config.js才是整个项目最关键的控制文件。3. 核心配置vite.config.js 一定要会改3.1 最常用的几个配置项vite.config.js是 vite 的配置文件项目启动、打包的信息都在这里控制。新人最容易用到的配置有以下三个。第一个是resolve.alias路径别名。默认情况下你要在代码里引用src下的文件得写一长串相对路径比如../../components/HelloWorld.vue页面层级一深就很难受。配置别名之后可以直接用/components/HelloWorld.vue这种简洁的写法import { fileURLToPath, URL } from node:url import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } } })第二个是server.host 和 server.port开发服务器监听配置。默认只监听 localhost也就是说只能在你自己电脑上访问。如果你的项目需要跑在局域网里用手机或者同一网络下的其他电脑测试页面就需要设置server: { host: 0.0.0.0, port: 5173, open: true }open: true的意思是启动后自动打开浏览器省去手动输入的步骤。第三个是server.proxy代理配置。前端开发时调用后端接口最常见的坑就是跨域。vite 里可以直接配置代理把域名相同的/api请求转发到本地后端服务server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }配置完以后你在代码里写的fetch(/api/user)会被自动转发到http://localhost:8080/api/user跨域问题就轻松解决了。这里的/api前缀可以自己定义只要后端接口也遵循这个规范就可以。3.2 环境变量与多环境配置在实际项目中开发环境和正式环境的接口地址往往不一样。vite 支持通过.env.development和.env.production文件来区分环境变量。在项目根目录新建.env.developmentVITE_API_BASE/api再新建.env.productionVITE_API_BASEhttps://api.example.com代码里通过import.meta.env.VITE_API_BASE读取运行时 vite 会根据当前启动模式自动加载对应文件。这样一来本地联调和发布上线都不用改代码省下不少麻烦事。需要注意环境变量必须用VITE_开头否则 vite 不会将它暴露给前端代码这也是很多新手容易踩的坑。4. 生产构建esbuild 与 terser 怎么选4.1 两者的核心区别项目开发完执行npm run build构建时vite 会压缩代码这个压缩环节涉及一个关键配置项build.minify。很多人在网上看到minify: terser和minify: esbuild两种写法但不知道有什么区别其实核心区别就三点压缩速度、压缩率、兼容性。esbuild 是用 Go 语言写的速度极快几乎不会在构建时让你等太久所以 vite 默认就使用它。terser 是 JavaScript 写的工具速度相对慢一些但压缩率更高生成的代码体积更小而且在处理一些老语法、特殊场景时更保守、更不会出错。对比项esbuildterser压缩速度极快较慢压缩效果产物稍大一点产物更小兼容性主要面向现代浏览器更擅长处理兼容老环境是否需要额外安装内置无需安装需要安装terser依赖4.2 实际配置与选用建议如果你的包体不大项目面向的是现代浏览器那么用默认的 esbuild 就足够了构建快、零配置体验很好。如果你发现构建出的包体积偏大或者你明确需要兼容一些比较老的环境、需要用 terser 做更精细的压缩比如剔除 console、debugger那可以这样配置npm install -D terser然后修改 vite.config.jsexport default defineConfig({ build: { minify: terser, terserOptions: { compress: { drop_console: true, drop_debugger: true } } } })上面这段配置会在构建时自动删除所有console.log和debugger语句正式包更干净也不会在浏览器控制台输出一堆调试信息。这个操作在生产环境很实用但要注意如果你在线上还需要查日志就别开drop_console否则排查问题时会很被动。4.3 简单聊聊 Vite 6 和 Rolldown看到这里你可能已经发现 vite 的构建链路中分包、依赖预构建是 esbuild生产打包底层用的其实是 Rollup。这个架构虽然已经很优秀但 vite 团队一直没停下来他们正在用 Rust 重写底层打包器这个项目叫 Rolldown。Vite 6 中Rolldown 作为实验性方向已经可以尝试了但目前它还在快速迭代生产环境不建议立刻大规模切换。对新手来说知道有这条技术趋势就够了。今年或明年等你熟练使用 vite 后可能正好赶上 Rolldown 稳定版发布届时打包性能还有一轮大提升。5. 常见问题与排查技巧5.1 启动报错或白屏的常见原因我遇到过最多的启动报错就是vite命令在运行时报 Node 版本不兼容或者安装依赖时网络原因导致某些包下载不完整。遇到这种情况我的排查顺序是第一步确认 Node 版本node -v如果低于 18立刻去升级。第二步删除node_modules和package-lock.json重新安装rm -rf node_modules package-lock.json npm install注意Windows 下没有rm -rf用rimraf或者在资源管理器里手动删除目录即可。这个方法能解决大部分奇怪报错因为依赖树装得不干净是本地环境最常见的隐性 bug。提示npm 安装依赖特别慢或者老失败时可以检查一下 npm 源是否设置得合理用国内镜像源可以明显缓解网络问题配置命令很常见搜一下就能找到属于基础操作。5.2 [vite:esbuild-transpile] 报错排查有些同学在运行项目时会看到类似[vite:esbuild-transpile] transform failed with 2 errors的报错。这个错误看着吓人其实本质是 esbuild 在转换某个 JS/TS 文件时遇到了语法解析问题。常见原因有三个一是项目里某个文件存在语法错误比如少括号、缺分号、用了更高级的语法特性但 esbuild 版本太老不支持这种去对应文件看一眼就能发现。二是某些依赖包与当前 vite 版本不兼容导致转换失败。三是node_modules里的缓存坏了。处理方式很简单先清掉缓存重新安装依赖再升级 vite 到最新版本然后重启项目。如果还报错就把报错信息里提到的文件路径复制出来打开那个文件重点检查语法。这个报错十有八九是文件本身的问题别一上来就重装系统。5.3 多人协作时的版本统一问题很多人用 vue3 vite 开发时会忽略.nvmrc文件或者engines字段的作用。如果你和小伙伴协作大家的 Node 版本不一致就会出现“我这儿跑得好好的你那儿报错”的尴尬情况。解决方法是在项目根目录创建.nvmrc文件里面只写一行20.11.0这样所有团队成员执行nvm use就能自动切换到统一的 Node 版本极大减少环境不一致带来的低级问题。如果在 Edge 浏览器里发现页面有时候关不掉右上角的最小化按钮或者界面异常大部分情况是某个 CSS 库和浏览器版本的小冲突先检查浏览器版本是否为最新再用开发者工具定位元素看看是不是某个动画或样式覆盖写歪了。这类兼容性 bug 不算少见但也别慌逐层排查就行。6. 下一步怎么走项目创建好、跑顺畅之后后面的路就很清晰了。先把模板语法和ref、computed、生命周期这几个核心概念过一遍比背什么“vue2 和 vue3 的区别”有用得多。等你熟悉了父子组件通信、pinia 状态共享再去看组合式函数composables和自定义指令基本就能应付日常业务开发了。我自己的体会是vue3 vite 的这套开发模式最大的优势不是“快”这么简单而是把前端开发的门槛降下来了项目结构干净、启动反馈快、报错信息也比较明确。你不需要一开始就懂底层原理只要会跑项目、会看报错、会改vite.config.js就已经能独立写完一个小型前端应用了。后面如果你遇到依赖安装半天下不完、打包体积越滚越大、旧项目升级 vite 主版本出现兼容问题这类事再回来翻这篇文章里的排查思路应该能省不少时间。慢慢来跑通第一个项目比什么都强。本文还有配套的精品资源点击获取