vite多页面项目需分四阶段实战：一、用vue模板初始化并重构为src/pages/多入口结构；二、配置vite.config.js指定input路径、别名及代理；三、验证构建输出、环境变量注入与css全局变量；四、排查白屏、hmr失效、样式丢失等典型问题。
直接上手做 Vite 构建综合实战项目，核心是“先搭骨架、再填内容、最后调优”，不追求一步到位，而是分阶段验证每一块是否真正生效。
一、初始化一个带结构的多页面项目
别从 vanilla 模板开始裸搭。用官方脚手架创建基础，再按多页结构重组织：
- 运行
npm create vite@latest my-app -- --template vue（选 Vue，便于后续加路由和组件） - 进目录后删掉默认的
src/App.vue和src/main.js，按多页逻辑新建src/pages/目录 - 每个页面放独立的
index.html+main.js，比如src/pages/home/index.html内容保持标准 HTML 结构，<script type="module" src="/src/pages/home/main.js"></script> - 确保
public/下放共用资源（如 favicon、logo），避免重复引用
二、配置 vite.config.js 支持多入口与开发体验
关键不是写全，而是让入口能被识别、路径能跳转、样式能复用：
- 在
vite.config.js中设置build.rollupOptions.input，明确列出每个页面 HTML 的绝对路径 - 加
resolve.alias，比如把@指向src，@pages指向src/pages，方便跨页面 import 公共模块 - 启用
server.proxy，例如代理/api到本地 mock 服务或后端，避免开发时跨域报错 - 开启
server.open = true，启动自动弹浏览器，省去手动输入地址
三、加入真实构建需求并验证效果
实战不是只跑起来，而是模拟上线前要面对的问题：
- 改
build.outDir为dist-prod，运行npm run build后检查输出目录是否生成多个 HTML 文件，且各自 JS/CSS 路径正确 - 在
.env.production里写VITE_API_BASE=https://prod-api.example.com，代码中用import.meta.env.VITE_API_BASE调用，构建后检查 dist 中是否被替换成实际值 - 加
css.preprocessorOptions.scss.additionalData注入全局变量文件，确保所有页面 SCSS 都能直接用$primary-color这类定义 - 用
build.rollupOptions.output.manualChunks把vue、lodash-es单独抽成 vendor chunk，观察打包后文件体积变化
四、调试与排查常见卡点
实战中最容易卡住的地方，往往就三类：
-
页面白屏：先看浏览器控制台有没有 404，大概率是
main.js路径写错或index.html中 script 标签没加type="module" -
HMR 不生效：确认修改的是当前打开页面对应的
main.js或组件，Vite 默认只热更当前模块图内文件 -
构建后样式丢失：检查是否用了未被 Vite 原生支持的 CSS 特性（如嵌套语法但没装插件），或 SCSS 变量路径没通过
additionalData正确注入 -
环境变量读不到：必须以
VITE_开头，且只能在代码中用import.meta.env.XXX访问，process.env在 Vite 里无效
