Vite 生产环境打包后静态资源 404 或页面空白怎么排查？

Question

仓乃文 · Accepted Answer

Vite 开发环境一切正常，打包部署后页面空白、静态资源 404，这是 Vite 初学者最常遇到的坑。90% 的原因是 base 路径配置不对或 Nginx 配置缺失。

问题分类与修复：
```bash
# 问题 1：所有资源 404
# 原因：base 路径配置错误
# 部署在子路径下必须配置 base
# vite.config.ts
export default defineConfig({
  base: "/admin/",  // 部署在子路径
  // 或用相对路径（通用方案）
  base: "./",
})

# 问题 2：首页正常，路由跳转后 404
# 原因：SPA 路由需要 Nginx 配置 fallback 到 index.html
# Nginx 配置
server {
  location / {
    try_files $uri $uri/ /index.html;  # 关键！
  }
}

# 问题 3：图片/字体 404
# 检查构建产物
ls -la dist/assets/

# 问题 4：跨平台路径问题（Windows 开发 + Linux 部署）
import path from "path"
export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src").replace(/\/g, "/"),
    },
  },
})
```

完整排查流程：
```bash
# 1. 检查 base 配置
# 根路径：base: "/"  子路径：base: "/admin/"  通用：base: "./"

# 2. 检查构建产物
npm run build && ls -la dist/

# 3. 本地预览构建产物
npx vite preview
# 模拟生产环境，确认打包后是否正常

# 4. 检查 Nginx 配置
# SPA 必须有 try_files
server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;
  location / {
    try_files $uri $uri/ /index.html;
  }
  location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

# 5. 检查环境变量
# Vite 环境变量必须以 VITE_ 开头才会暴露给客户端
```

Docker 部署配置：
```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
```

补充说明：
- 规则：部署前必须 npx vite preview 验证构建产物
- base: "./" 是最通用的配置，但 CDN 场景需要用绝对路径
- SPA 必须配 Nginx try_files，否则路由跳转后刷新 404
- 环境变量必须以 VITE_ 开头，否则 import.meta.env 拿不到
- 静态资源加 contenthash + 长期缓存，HTML 不缓存