Vite构建失败最典型表现是dev正常、build报Rollup failed to resolve import，根因是开发与构建环境路径解析机制差异暴露代码隐性错误：/ @/应改为@/、public资源须用绝对路径、部署需配base和history fallback。
Vite 构建失败，最典型的表现就是：本地 npm run dev 一切正常，一执行 npm run build 就报红，错误集中在 Rollup failed to resolve import。这不是 Vite 或 Rollup 的 bug，而是开发与构建环境对路径解析的机制差异暴露了代码里的“隐性错误”。下面从三个最常踩的坑切入，讲清楚怎么快速定位、修复和预防。
别名路径写成 "/@/" 而不是 "@/ "
这是最高频的构建翻车点。比如写了：
import UserCard from '/@/components/UserCard.vue'import { api } from '/@/api/index.ts'
这类 /@/ 开头的写法，在开发服务器中能跑通，是因为 Vite 的 dev server 内置了对根路径别名的宽松解析（类似自动 fallback 到 src/），但 Rollup 在构建阶段是严格按配置解析的，它根本不认识 /@/ 这个前缀。
正确写法必须是 @/（不带开头斜杠）：
import UserCard from '@/components/UserCard.vue'import { api } from '@/api/index.ts'
同时确认 vite.config.ts 中已正确定义 alias：
export default defineConfig({
resolve: {
alias: {
'@': path.resolve(__dirname, 'src')
}
}
})
public 目录资源引用路径不规范
把图片、字体、JSON 等静态资源放在 public/ 下本意是跳过构建处理，直接复制到 dist/ 根目录。但引用时如果写相对路径或带 /@/，就会在构建后 404。
✅ 正确方式：用绝对路径（以 / 开头，对应部署后的根路径）：
-
<img src="/logo.png" alt="JS 中 Vite 构建排错指南与经典案例复盘" >→ 对应public/logo.png -
fetch('/config.json')→ 对应public/config.json
❌ 错误写法：
-
<img src="logo.png" alt="JS 中 Vite 构建排错指南与经典案例复盘" >（相对路径，可能变成/dist/src/logo.png） -
<img src="/@/assets/logo.png" alt="JS 中 Vite 构建排错指南与经典案例复盘" >（混淆了别名与 public 规则）
注意：若项目部署在子路径（如 https://example.com/myapp/），需同步配置 base: '/myapp/'，否则 /logo.png 会请求错位置。
构建产物部署后白屏或资源 404
构建成功 ≠ 部署成功。常见原因有三：
-
base 配置缺失：默认
base: '/'，部署到子路径时 JS/CSS 请求路径全错；应显式设为实际路径，如base: '/admin/' -
Nginx 未配 history fallback：Vue Router 使用
history模式时，刷新二级路由（如/user/list）会 404；Nginx 需添加：location / { try_files $uri $uri/ /index.html; } -
缓存未更新：JS 文件带哈希，但
index.html没缓存控制，CDN 或浏览器可能长期缓存旧 HTML，导致新 JS 加载失败；建议给index.html设置Cache-Control: no-cache
