——为什么静态资源会在生产环境 404？

使用者痛点：

• 阶段页面预览完美，图片、字体等资源全部加载成功。
• 执行 vite build 打包后部署到服务器，页面出现空白或样式错位。
• 浏览器控制台报错：Failed to load resource: server responded with a status of 404 。
• 花费大量时间去排查，却始终找不到根本原因。

Vite 以极速的冷启动和高效的热更新著称。但在生产建立时如果不正确处理静态资源方法，一样会让人抓狂。怎么说呢，

问题现象

从开发到生产常见的异常表现包括：

1. 本地 DevServer 下图片、字体、背景图均能正常显示。
2. 打包后的 dist 部署到真实服务器后部分资源返回 404。
3. 控制台错误信息类似：GET https://example.com/assets/logo.png 404

主要原因分析

. 静态资源方法不匹配

Vite 在生产建立时会把所有被引用的资源复制到 assets目录，并加上哈希实现缓存。若代码中写死了方法或使用了错误的相对/绝对方法。就会导致最终生成的文件与引用不一致，从而出现 404。

. 相对方法 vs 绝对方法混用

• 相对方法: 在开发环境下由 DevServer 自动解析，但在生产环境必须相对于生成文件所在位置。
• 绝对方法: 会基于 Vite 的 base 配置解析。如果未配置或配置错误，则始终指向站点根目录。

. CSS 中的 url

Cascade Style Sheets 中引用资源时一样遵循相对方法规则。若在 CSS 中写成 /images/bg.png则在子目录部署时会失效。

. publicDir/assetsDir 配置冲突

• publicDir: 用于存放无需的文件，会原样复制到输出根目录。
• assetsDir: 用于存放经 Rollup 打包并加哈希的资源。若误将需要哈希处理的文件放进了 public。那么这些文件不会被重命名，也不会被正确引用。
• base: 部署到子目录时必须同步修改，否则所有资产仍按根目录寻找。

. 子目录部署导致的方法偏移

If your app lives under a sub‑path like /app/,but Vite’s default base is “/”,every generated URL will point to root,causing a cascade of 404 errors.

. 动态导入或字符串拼接未使用 Vite 的模块解析机制

• Dynamically constructing URLs bypasses Vite’s static analysis。so assets won’t be emitted.
• Lack of @vitejs/plugin-react‑refresh/`import.meta.url`** usage leads to missing hash‑mapped files.

方法 & 常用方法 ✅

. 正确引用静态资源

• ESM 导入方式：

  import logoUrl from './assets/logo.png';const img = new Image;
  说起来，img.src = logoUrl;document.body.appendChild;

• Cascading style sheets：CSS 中使用相对方法且不要手动添加前导斜杠。例如这方面，

  background: url;/* 相对于当前 CSS 文件 */

. 配置正确的 base

import { defineConfig } from 'vite';export default defineConfig({
// 部署在 https://example.com/app/ 时
base这方面。'/app/',// 与实际子目录保持一致
});

. 区分 #publicDir#  和 #assetsDir#

• Public Dir用于直接复制且不做 hash 的文件；放置如 robots.txt、favicon.ico 等无需改名的静态文件。
• Assets Dir用于需要经过 Rollup 编译并加 hash 的资源；默认是 `assets`。
• 确保图片、字体等需缓存调整的资源放在 `src` 或 `assets` 文件夹内，而不是 `public`。

. 检查产出结构并匹配服务器路由

典型 Vite 打包产出结构：

dist/
├── assets/
│ ├── logo.9c1a8b.png
│ └── main.c1d5f6.css
├── index.html
└── favicon.ico

确认 Nginx / Apache 等服务器已配置好对应路由，例如 Nginx 可使用：

location /app/ {
try_files $uri $uri/ /app/index.html;怎么说呢，}

. 动态导入要用 Vite 支持的方法

• 使用 **import.meta.glob** 或 **new URL** 获取运行时 URL：

  const images = import.meta.glob;怎么说呢，const imgUrl = new URL.href;

• 避免手动字符串拼接导致 Vite 无法检测到依赖关系。其实，

实战案例 – 子目录部署导致图片 404 🚧

问题描述

项目发布至 https://example.com/app/ 后页面中的 logo 图片请求地址为 https://example.com/assets/logo.png。返回 404，

排查过程

1. 打开 `dist/index.html`，发现 `` 使用了根方法。
2. 检查 `vite.config.js`，发现没有配置 `base`。
3. 添加 `base: '/app/'` 并重新建立。

结果验证

重新部署后请求地址变为 https://example.com/app/assets/logo.9c1a8b.png，图片成功加载。按理说，✅

& 快速检查清单 ✅

1. 统一使用 ES 模块方式引入资源
2. 部署子目录务必配置 `base` 与 CDN/服务器映射保持一致
3. 区分 publicDir 与 assetsDir。用途错位会导致未被处理或重复处理
4. 检查产出结构是否与服务器路由匹配
5. 避免动态字符串拼接导致 Vite 无法收集依赖

掌握以上要点，你就能彻底摆脱 Vite 打包后静态资源突发 404 的问题，让项目上线无忧！🎉

---