掌握Vite构建需理解开发与构建模式在路径、资源、模块上的差异：/@/需显式配置别名，@/不被默认识别；动态拼接路径会导致生产404，应改用import.meta.glob或public目录；proxy顺序须由细到粗；source map应剥离源码内容以防泄露。
掌握 Vite 构建的常见陷阱与调试技巧，关键不是背命令，而是理解“开发模式”和“构建模式”在路径解析、资源处理、模块加载上的根本差异。很多问题表面是报错，根源其实是两种模式行为不一致被掩盖了。
路径别名失效：/@/ 和 @/ 的区别必须分清
Vite 中 /@/（带前导斜杠）和 @/（不带）完全不是一回事：
-
/@/ 是一个“绝对路径别名”，需在
vite.config.js中显式配置resolve.alias，例如：{ '/@/': path.resolve(__dirname, 'src') }；否则 Rollup 构建时会直接报failed to resolve import "/@/xxx" - @/ 是 Vue CLI 或某些模板遗留的习惯写法，Vite 默认不识别——如果没配 alias，开发环境能跑只是因为 Vite 的 dev server 做了宽松 fallback，构建阶段就会彻底失败
- 排查建议：在
vite.config.js开头加console.log('alias:', config.resolve?.alias)，确认别名是否真实生效；存量项目可全局搜索import.*?["@/|/@/]，统一替换为已配置的别名格式
静态资源动态引用：拼接路径在生产环境必然 404
像 const src = './assets/' + name + '.png' 这类写法，开发时看着正常，构建后图片全丢——因为 Rollup 只处理 静态字符串路径 和 显式 import，对运行时拼接无感知。
- 正确做法一：用
import.meta.glob预加载所有可能用到的资源：const imgs = import.meta.glob('./assets/*.png')，再通过await imgs['./assets/xxx.png']()获取 - 正确做法二：把不常变的资源放
public/目录下，直接用/logo.png这样的绝对路径引用（注意开头无点，也不走模块解析） - 验证方式：构建后打开
dist/目录，检查对应图片是否存在；若缺失，说明该资源未被 Rollup 收入依赖图
代理配置顺序错误：/api 和 /api/v1 谁先谁后很关键
Vite 的 proxy 底层用的是 http-proxy-middleware，匹配规则是从前到后、前缀匹配、命中即止。如果配置顺序是：
'/api': { target: 'http://old' },<br>'/api/v1': { target: 'http://new' }
那么所有 /api/v1/xxx 请求都会被第一个规则捕获并错误转发。
- 修复方法：把更具体的路径放在前面，即先写
/api/v1，再写/api - 进阶技巧：用正则精确匹配，例如
^/api/v1/加^/api(?!\S*/v1)避免歧义 - 调试手段：启动 dev server 后访问
http://localhost:5173/__vite_ping确认服务正常；再在浏览器 Network 面板看请求是否被代理（Status 显示 200 且响应头含X-Proxy-By: vite）
混淆与 Source Map 冲突：保护代码不能牺牲可维护性
用 javascript-obfuscator 混淆后开启 sourceMap: true，看似方便调试，实则埋下隐患——Source Map 文件一旦泄露，就能近乎还原原始逻辑。
- 安全做法：构建时生成 source map，但通过
rollupOptions.output.sourcemapExcludeSources = true剥离源码内容，只保留位置映射 - 更稳妥方案：CI 流程中单独存档 source map 到内部存储（如 S3），线上 dist 目录完全不包含
.map文件 - 验证方式：检查构建输出目录是否有
xxx.js.map；若有，用文本编辑器打开，确认里面不含sourcesContent字段
