Vue3 + Vite 项目搭建

我为什么从 Vue CLI 切到 Vite

去年我做第二个全栈项目时，还在用 Vue CLI 4.x scaffolding 新页面。热更新在开发阶段要等三到五秒，每次改个样式都要盯着浏览器转圈。后来听同事提了一句 Vite，我半信半疑地试了一下，第一次热更新刷新几乎 instantaneous，我当时就懵了——这差距也太大了吧。

Vite 的核心思路是把构建时的预处理工作挪到开发服务器运行时，用浏览器原生 ESM 能力按需加载。简单说就是：启动快，改什么都快。对于我这种一天改几十次前端代码的人来说，时间累积下来相当可观。

环境准备与第一个坑

先确认 Node 版本。Vite 要求 Node 18+，我当时的服务器还是 16.x，直接报错 Error: Cannot find module 'vite' 这种莫名其妙的东西。排查了半天，最后发现是 Node 版本不兼容。

创建项目的命令很简单：

npm create vite@latest my-vue3-app -- --template vue
cd my-vue3-app
npm install
npm run dev

但这里有个坑：如果网络不好，npm install 可能会卡在某个 peer dependency 上。我遇到过 @vitejs/plugin-vue 版本和 Vue 版本不匹配的问题，解决方法是先装 Vue 再装 Vite 插件，或者直接用 pnpm 的 lockfile 机制。

项目结构到底长什么样

进入 src 目录，你会看到：

src/
├── assets/     # 静态资源
├── components/ # 公共组件
├── App.vue     # 根组件
└── main.js     # 入口文件

.vue 单文件组件（SFC）是 Vue3 的默认写法。<script setup> 语法糖是我最推崇的特性之一，它把 setup() 函数里的变量和函数直接暴露到模板，省了大量 return 语句。

我用 <script setup> 改写了一个计数器组件，对比之前的 Options API，代码量直接少了三分之一，而且逻辑更集中。

Vite 配置文件的几个实用技巧

项目根目录的 vite.config.js 是我最常改的文件。默认内容很简单，但实际开发中你需要处理代理、路径别名、环境变量。

我踩过的第一个坑是路径别名。Vite 默认用 @ 指向 src，但如果你像我一样从 Vue CLI 迁移过来，已经写了几十个 @/views/xxx 的导入，改起来会疯掉。好在 Vite 的 resolve.alias 配置可以完美继承：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
})

第二个坑是跨域。开发环境用 server.proxy 转发，但生产环境需要 Nginx 配置。我早期忘记改 Nginx，上线后接口全部报 404，排查了一个多小时才想起 Vite 的 dev server 代理不会带到生产环境。

环境变量的正确姿势

Vite 用 .env 文件管理环境变量，这点比 Vue CLI 直观。在根目录创建：

VITE_API_BASE=http://localhost:8080

代码里通过 import.meta.env.VITE_API_BASE 读取。注意变量必须以 VITE_ 开头，否则 Vite 不会暴露到客户端。我当时图方便写了 API_SECRET，结果页面报 undefined，查文档才知有这个约定。

总结

Vite + Vue3 的组合确实大幅提升了前端开发体验。启动速度从 Vue CLI 的十几秒降到了秒级，热更新更是几乎无感。但迁移过程中需要注意 Node 版本、插件兼容性、代理配置和环境变量规范这几个关键点。把这些坑提前踩平，后续开发会顺畅很多。以后有新同事问我前端技术栈选型，我肯定会把 Vite + Vue3 放在推荐列表最前面——当然，前提是他已经装好了 Node 18+。