Vue3 + Vite 项目从零搭建到上线：踩坑实录
Vue先给结论：Vue3 + Vite 从零到上线，最省心的路径就一句——用官方 create-vue 脚手架选好 TypeScript/路由/状态/规范，再按「路由层 → 状态层 → 请求层」三层组织代码，最后 build 出 dist 丢给静态托管。新手 90% 的坑，集中在 Node 版本不对、路径别名没配、跨域代理漏写、以及 SPA 上线后刷新 404 这四处。
一、环境准备
-
| | | |
| --- | --- | --- |
- Node 版本：Vue 官方要求
^20.19.0 || >=22.12.0，老 Node 直接报兼容错。用 nvm（Windows 用 nvm-windows）切到 22：nvm install 22 && nvm use 22。 - 包管理器：2026 年社区主流是 pnpm，磁盘占用小、幽灵依赖管控严：
npm install -g pnpm，国内可pnpm config set registry https://registry.npmmirror.com加速。 - 编辑器：VS Code + 官方插件「Vue - Official」（原 Volar），务必禁用旧的 Vetur，两者共存会报错。
二、create-vue 脚手架
官方脚手架一条命令拉起，交互选项按需选：
pnpm create vue@latest # 交互选项建议： # ✔ Project name: … my-vue-app # ✔ Add TypeScript? … Yes # ✔ Add Vue Router? … Yes # ✔ Add Pinia? … Yes # ✔ Add ESLint / Prettier? … Yes
想完全自己掌控配置，也可以用极简的 pnpm create vite my-app --template vue-ts，只给骨架。新手建议走官方脚手架，规范直接开箱即用。
三、目录规划（src 分层）
别把所有逻辑堆在组件里，按职责分层，后面才好维护：
src/ ├─ views/ 页面级组件（按路由拆） ├─ components/ 可复用 UI 组件 ├─ composables/ 组合式函数（抽公共逻辑，如 useUser） ├─ api/ 请求层（所有接口集中在这） ├─ store/ Pinia 状态（user、cart 等） ├─ router/ 路由表 └─ utils/ 工具函数
四、Vite 配置要点
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
},
server: {
proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true } }
},
build: { target: 'chrome120' }
})
- @ 别名：
import '@/api/user'不用写一长串相对路径。 - proxy 跨域：开发时前端 5173、后端 3000，配
/api代理把请求转给后端，规避浏览器跨域。 - build target：按目标用户浏览器设，太低失去新语法优化，太高老浏览器跑不动。
五、三层：路由 / 状态 / 请求
- 路由 Vue Router：页面级组件放
views，懒加载() => import('@/views/Home.vue')减小首包。 - 状态 Pinia：跨组件共享的数据（登录用户、购物车）放 store，别用 props 一层层透传。
- 请求层 axios：在
api/里封装一个带 baseURL、拦截器（自动带 token、统一报错）的实例，组件里只调业务函数。
六、构建优化与上线
pnpm build # 产物在 dist/ pnpm preview # 本地预览构建结果
- 把
dist/整个目录丢给静态托管（Nginx、对象存储、Vercel/Netlify 都行）。 - SPA 路由 fallback：Vue Router 用 history 模式时，用户直接访问
/about或刷新会 404，需在托管侧配「所有路径回退到 index.html」。 - 体积优化：路由懒加载 + 按需引入组件库；用
rollup-plugin-visualizer看是谁把包撑大的。
七、五个常见坑
| 坑 | 原因 | 规避 |
|---|---|---|
| Node 版本报错 | 用了太老的 Node | 切到 22（nvm use 22），重装依赖 |
| @ 别名找不到 | vite.config 没配 alias | 按上面配 resolve.alias |
| 开发调接口跨域 | 前端直连后端域名 | 配 server.proxy，开发期走 /api |
| 上线刷新 404 | SPA 没配 fallback | 托管侧所有路径回退 index.html |
| Vetur 与 Volar 打架 | 两个 Vue 插件共存 | 禁用 Vetur，只留 Vue - Official |
八、FAQ
Q：Vite 现在哪个版本稳？
截至 2026-11，Vite 已迭代到 8.x（Rolldown 统一打包，构建更快），Vue 稳定在 3.5.x。用 create vue@latest 拉到的就是当前稳定组合，别手动锁过低版本。
Q：TypeScript 必须上吗？ 不是必须，但 2026 年新项目几乎都上 TS，类型能帮你挡掉大量低级错误，强烈建议选 Yes。
Q：组件库（Element Plus 等）怎么引？ 按需引入最稳，别全量 import 把包撑爆；具体按组件库官方 Vite 插件配置。
Q：和 UniApp 什么关系？ UniApp 是跨端方案（见 frontend-miniprogram-1），原理不同；纯 Web 项目用 Vue3 + Vite 即可。
小结
Vue3 + Vite 的标准姿势：create-vue 选好 TS/路由/Pinia → src 按 views/components/composables/api/store 分层 → vite.config 配 @ 别名和 /api 代理 → 路由懒加载 + Pinia 管状态 + 封装 axios → build 出 dist 上线并配 SPA fallback。新手先把「Node 版本、别名、代理、刷新 404」这四个坑避开，就能顺利跑通第一个上线项目。具体版本与配置以 Vue / Vite 官方文档当天说明为准。