Vite项目部署后静态资源404错误

Question

Vite项目部署后静态资源404错误常见于生产环境路径配置不当。典型问题是打包后资源路径默认为相对路径（`/assets/`），但部署到非根目录（如GitHub Pages子路径）时未正确设置`base`配置项，导致浏览器无法定位JS、CSS等文件。此外，服务器未配置支持History模式或缺少静态资源MIME类型，也会引发404。需在`vite.config.js`中正确设置`base: './'`并确保服务器正确托管静态资源。

Answer 1

1. 问题背景与现象描述

在将基于 Vite 构建的前端项目部署至生产环境后，开发者常遇到静态资源（如 JS、CSS、图片等）返回 404 错误的问题。这类问题多出现在非根路径部署场景中，例如 GitHub Pages 的子路径（/my-vite-app/）、Nginx 子目录代理或 CDN 路径映射时。

浏览器控制台通常显示如下错误：

GET https://example.com/assets/index.abc123.js net::ERR_ABORTED 404 (Not Found)

这表明浏览器尝试从错误路径加载资源，根本原因在于构建产物中的资源引用路径未正确适配部署上下文。

2. 核心成因分析

• 默认 base 配置为 "/"：Vite 默认使用绝对路径 /assets/ 引用静态资源，适用于部署在域名根目录的情况。
• 未设置正确的 base 路径：当应用部署在子路径下（如 /app/），但未在 vite.config.js 中配置 base: './' 或 base: '/app/'，导致资源请求仍指向根路径。
• 服务器未支持 History 模式：SPA 应用依赖前端路由，若服务器未将所有非静态资源请求回退到 index.html，则直接访问子页面会触发 404。
• MIME 类型缺失或错误：某些老旧服务器或自定义服务未正确识别 .js、.css 文件的 MIME 类型，导致资源无法执行。

3. 解决方案层级递进

3.1 修改 Vite 构建配置：base 设置

在 vite.config.js 中根据部署路径调整 base 字段：

export default defineConfig({
  base: './', // 相对路径，适合 GitHub Pages 子目录
  // 或
  base: '/my-project/', // 绝对子路径，匹配服务器部署位置
})

该配置影响所有生成的资源链接（包括动态导入、CSS background-url 等），确保其相对于 HTML 文件定位。

3.2 构建产物路径验证

执行 vite build 后检查 dist/index.html 中的资源引用是否已更新：

配置项	生成路径示例	适用场景
base: '/'	<script src="/assets/app.js">	部署于根域
base: './'	<script src="./assets/app.js">	GitHub Pages 子目录
base: '/admin/'	<script src="/admin/assets/app.js">	Nginx 代理 /admin/

3.3 服务器配置优化

以 Nginx 为例，需确保静态资源托管和 history fallback 正确：

location /my-app/ {
    alias /var/www/my-app/;
    try_files $uri $uri/ /my-app/index.html;
}

# 显式声明 MIME 类型（可选增强）
types {
    text/javascript js;
    text/css css;
}

对于 GitHub Pages，其自动支持静态托管和相对路径，但仍需设置 base: './'。

3.4 部署流程自动化建议

结合 CI/CD 动态设置 base 值，避免硬编码：

export default defineConfig(({ mode }) => ({
  base: mode === 'production' ? '/my-app/' : '/',
}))

4. 故障排查流程图

graph TD
    A[页面加载失败, 静态资源404] --> B{检查network面板路径}
    B -->|路径以/开头| C[确认部署是否在根目录]
    C -->|否| D[修改vite.config.js中base为./或子路径]
    C -->|是| E[检查服务器root配置]
    B -->|路径正确但404| F[检查MIME类型或缓存]
    D --> G[重新构建并部署]
    G --> H[验证index.html中资源链接]
    H --> I[测试跨路径访问]
    I --> J[完成]

5. 扩展思考：现代部署架构下的适应性

随着微前端、边缘计算和 Serverless 架构普及，Vite 应用可能被部署在高度动态的路径环境中。此时，仅靠构建期 base 配置已不足，需引入运行时路径解析机制，如通过注入全局变量 window.BASE_URL 实现动态资源定位。

此外，在 CDN 分发场景中，应结合版本哈希与缓存策略，防止旧路径残留引发连锁 404。

对于大型组织，建议建立统一的部署规范模板，集成 Vite + Docker + Nginx 的标准化镜像，内建路径兼容逻辑。