2024年从零搭Vue3项目选Vite还是Vue CLI？新手踩过的坑全说透

这两年问Vue3项目搭建工具的人特别多，身边还有同事用了错误的工具版本差点耽误上线，前阵子我带实习生搭一个基础的后台管理原型，一开始选了过时的Vue CLI 4，结果跑热更慢、配置TS插件卡半天，最后花了一下午才换回来Vite 5，现在就结合我自己和团队这大半年踩过的坑、官方工具链的更新，还有身边前端圈的实际使用情况，把整个问题拆解清楚，连新手常忽略的环境准备、插件选择、甚至项目上线前的配置小技巧,都会一起说。

先给个结论：2024年搭Vue3项目，99%的场景选Vite

先别急着划走，不是说CLI完全没用了，而是Vite从2022年底Vue3成为默认推荐工具链之后，不管是生态、性能还是易用性，都追上甚至超过了CLI，举个很直观的例子，我之前用CLI 5搭一个带路由、状态管理、Element Plus的后台模板，第一次install加第一次启动，加起来差不多8分钟；用Vite 5的话，install大概1分钟，启动只用3秒，热更是毫秒级更新——实习生甚至以为项目没跑起来，刷新页面才发现组件已经变了，而且现在Vite已经迭代到5.x版本，很多之前只有CLI有但Vite没有的功能，比如插件预设、环境变量拆分、打包优化这些,都做得更完善了。

也不是所有场景都选Vite，比如你要维护一个旧的Vue2+Vue3混合项目，或者依赖某些非常小众的、只适配Webpack的插件，那还是得用CLI；不过这种场景在2024年已经很少见了,很多主流的插件几乎都有Vite版本了。

那搭Vite版Vue3项目前，新手最容易漏的环境准备

选好工具只是第一步，很多新手项目跑不起来，都是环境没配对，首先就是Node.js的版本，之前实习生就用了Node.js 14，结果连Vite 5都装不上，现在查过最新的Vue官方指南，Vite 5.x和Vue3.4+需要Node.js 18.0或者20.x的LTS版本——注意是LTS（长期支持版本），别去装那些奇数版本的尝鲜版，尝鲜版可能会有不稳定的问题,新手遇到问题根本找不到解决办法。

然后就是包管理器的选择，现在主流的有npm、yarn、pnpm，团队现在统一用pnpm了，因为pnpm节省磁盘空间、安装速度比npm和yarn快很多，而且它的依赖隔离做得更好，不会出现“幽灵依赖”导致项目跑不起来的情况，不过如果是第一次用pnpm的话，得先全局安装一下，安装命令很简单，直接在终端输入就行，还要把npm镜像源换成国内的，比如淘宝镜像，不然install的时候可能会因为网络问题装不上依赖，换源的命令，不管用哪个包管理器都差不多，新手可以直接用nrm或者pnpm自带的换源工具，一键切换就行,不用记那么长的镜像地址。

新手可能会忽略IDE的配置，这个虽然不是必须的，但能大大提高开发效率，比如VS Code，一定要装Volar插件，这个插件是Vue官方推荐的VS Code插件，能提供Vue3的语法高亮、代码补全、错误提示这些功能；还要把旧的Vetur插件禁用掉，不然Vetur是给Vue2用的，和Volar会冲突，还可以装ESLint、Prettier这些插件，用来规范代码格式，避免团队协作的时候大家写的代码风格不一样,看起来很乱。

从零搭一个带常用的Vite版Vue3后台模板的详细步骤

环境准备好之后，就可以正式开始搭项目了，首先是创建项目的命令，不管用哪个包管理器都差不多，比如用pnpm的话，就是在终端输入pnpm create vite@latest，然后按照提示一步步来就行——注意是vite@latest，别漏了latest，不然可能会安装旧版本的Vite，首先会让你输入项目名称，比如vue3-admin-template；然后会让你选择框架，选Vue就行；然后会让你选择变体，这里推荐新手选TypeScript+Vue Router+Pinia+ESLint+Prettier这个预设，后面还会问你要不要加Tailwind CSS，要不要加Playwright测试框架做E2E测试，新手如果暂时不需要的话,可以直接跳过。

创建好项目之后，先进入项目目录，然后install依赖，启动项目，看看能不能正常运行，启动之后，就可以开始配置一些常用的东西了，比如别名配置、环境变量配置、打包优化配置这些。

别名配置，默认情况下，Vite是支持@作为src的别名，但有些新手可能不知道怎么用，或者在TS环境下会报错，这个时候就需要配置一下vite.config.ts文件和tsconfig.json文件，在vite.config.ts文件里，需要在resolve.alias里配置一下@的路径；在tsconfig.json文件里，需要在compilerOptions.paths里配置一下@的路径，这样TS才能识别@的别名。

然后是环境变量配置，Vite的环境变量和CLI的不一样，新手很容易搞混，Vite的环境变量需要放在项目根目录下的.env文件里，而且变量名必须以VITE_开头，不然在客户端代码里是读取不到的，比如可以创建.env.development文件（开发环境）、.env.production文件（生产环境）、.env.staging文件（预发布环境），然后在这些文件里定义不同的变量，比如API的地址，在客户端代码里，用import.meta.env.VITE_API_URL来读取；在vite.config.ts文件里，用process.env或者loadEnv函数来读取。

接下来是插件的安装和配置，比如路由插件，刚才选预设的时候已经安装了，但新手可能不知道怎么用，这个时候可以去看一下Vue Router的官方文档，简单来说就是先定义路由规则，然后创建路由实例，最后在main.ts文件里挂载到Vue应用上，然后是UI组件库，比如现在主流的Element Plus、Ant Design Vue这些，推荐新手用Element Plus，因为它的中文文档比较全，而且组件比较丰富，适合后台管理系统，安装Element Plus也很简单，直接用pnpm install element-plus @element-plus/icons-vue就行，然后在main.ts文件里全局引入或者按需引入——按需引入的话，能减少打包后的体积，推荐新手用按需引入的方式，现在Vite已经支持unplugin-auto-import和unplugin-vue-components这两个插件,一键就能配置好按需引入。

然后是打包优化配置，新手可能觉得打包后的体积太大，上线之后加载速度太慢，这个时候就可以配置一下vite.config.ts文件里的build选项，比如开启tree-shaking、代码分割、压缩这些功能，还可以安装一些打包优化的插件，比如vite-plugin-compression插件，用来开启gzip或者brotli压缩,进一步减少打包后的体积。

搭完项目后，新手上线前容易踩的坑

搭完项目之后，上线前还有几个坑新手容易踩，第一个坑是路由的history模式，很多新手直接用history模式，然后打包之后刷新页面就会出现404的情况，这个时候就需要配置一下服务器的重定向规则，比如Nginx的话，需要在nginx.conf文件里配置一下try_files $uri $uri/ /index.html;；Apache的话，需要配置.htaccess文件，如果是部署到GitHub Pages或者Gitee Pages的话，还需要用hash模式,或者配置一下publicPath和重定向规则。

第二个坑是publicPath的配置，新手可能不知道怎么配置publicPath，然后打包之后部署到服务器的子目录下，就会出现静态资源加载失败的情况，这个时候就需要在vite.config.ts文件里配置一下base选项，比如部署到子目录/admin/下，就把base设置为/admin/。

第三个坑是环境变量的配置，刚才已经说过了，变量名必须以VITE_开头，不然在客户端代码里是读取不到的，env文件里的变量不能有空格,不然也会读取不到。

第四个坑是打包后的代码没有压缩，新手可能不知道怎么开启压缩功能，这个时候就可以检查一下vite.config.ts文件里的build.minify选项，默认是开启的，不过可以设置为esbuild或者terser，esbuild压缩速度快，terser压缩体积小，推荐新手用esbuild，如果对体积要求比较高的话,可以用terser。

第五个坑是没有测试打包后的代码，很多新手搭完项目之后直接上线，结果上线之后才发现有问题，这个时候就可以先在本地测试一下打包后的代码，测试的命令是pnpm run build，然后pnpm run preview,这样就能在本地预览打包后的代码了。

其实搭建Vue3项目其实不难，只要选对工具、配好环境、按照步骤来，就能很快搭出一个常用的后台管理模板，搭完模板之后，还要不断地学习Vue3的新特性，比如Composition API、Teleport、Suspense这些，才能更好地开发项目，还要不断地优化项目，比如优化性能、优化代码结构、优化用户体验这些,才能让项目变得更好。