Vite构建本质是ES模块静态分析+Rollup打包，开发时按需加载、不打包，生产时才打包优化；public资源直拷贝、src资源经模块解析并哈希，路径和环境变量需严格对齐配置。
理解 Vite 构建的本质，别当“配置搬运工”
Vite 的构建（vite build）不是 Webpack 那套“打包即编译”的逻辑，而是基于 ES 模块的静态分析 + Rollup 打包。它默认只对 .js(x)、.ts(x)、.css 等资源做处理，不会自动识别或加载非标准路径、动态 require、HTML 中 script 标签的内联 JS。很多“构建后白屏”“资源 404”问题，根源是误以为 Vite 和开发服务器行为一致。开发时的 HMR 和构建时的产物生成是两套机制，不能靠 dev 通就默认 build 也通。
路径相关坑：public 目录与 base 配置必须对齐
Vite 中资源引用分两类：
-
public 目录下的文件：直接拷贝到 dist 根目录，引用时用绝对路径（如
/logo.png），不走构建系统； -
src 下的资源：需被模块系统解析，路径是相对或裸导入（如
import img from '@/assets/logo.png'），构建后自动哈希并重写路径。
常见错误：
– 在 HTML 中写 <img src="logo.png">（相对路径），但没放 public 里，也没加 /，导致构建后路径错乱；
– 修改了 base: '/my-app/'，但忘了更新 HTML 中的 <base href="/my-app/"> 或 public 资源引用前缀；
– 使用 import.meta.env.BASE_URL 动态拼接路径时，漏掉末尾斜杠（如 ${BASE_URL}logo.png 在 base 为 /app/ 时变成 /app/logo.png 正确，但 base 为 /app 时变成 /applogo.png 就错了）。
环境变量与代码分割：DEV/BUILD 不同行为要显式控制
Vite 只将以 VITE_ 开头的变量注入客户端（通过 import.meta.env），且仅在构建时进行静态替换（类似宏）。这意味着：
-
console.log(import.meta.env.VITE_API_URL)在构建后会被替换成字符串字面量，但const key = 'VITE_API_URL'; console.log(import.meta.env[key])会失效（无法静态分析）； -
if (import.meta.env.DEV) { ... }中的代码，构建时会被 Rollup 的tree-shaking完全移除——这是特性不是 bug，但若你写了if (import.meta.env.PROD) { initSentry() }却发现 Sentry 没初始化，大概率是因为条件判断被优化掉了，可改用import.meta.env.PROD === 'true'强制保留判断逻辑； - 动态
import()默认触发代码分割，但若路径含变量（如import(`./pages/${page}.vue`)），Vite 无法静态分析，会导致构建失败或 fallback 到完整 chunk —— 应限定为已知枚举值，或配合import.meta.glob显式声明。
插件与自定义构建：别绕过 Vite 的 resolver
遇到“找不到模块”不要急着加 resolve.alias 或改 optimizeDeps.include。先确认：
- 是否用了非标准扩展名（如
.jsx却没配esbuild.jsxInject或启用jsx: 'automatic'）； - 是否在
vite.config.ts中错误地覆盖了resolve.extensions，删掉了'.js'或'.ts'； - 是否在插件中手动读取文件但没走 Vite 的
this.resolve()，导致路径解析脱离 Vite 上下文（例如自定义 Markdown 插件里直接fs.readFileSync('./foo.md')，而非await this.resolve('./foo.md')）； - SSR 构建时（
vite build --ssr），Node 内置模块（如fs、path）默认不提供 polyfill，需显式配置ssr.noExternal或用rollupOptions.external排除。
不复杂但容易忽略。
