Vite 构建时字体与背景图失效的解决方案

vite 项目执行 `npm run build` 后，scss 中通过相对路径引用的字体（`@font-face`）和背景图无法正常加载，根本原因是 vite 对 `src/` 外部资源路径不识别，且未正确处理静态资产的拷贝与解析。

在 Vite 中，所有静态资源（如字体、图片）必须位于受构建系统管理的目录内，才能被自动解析、哈希重命名、并正确注入到构建产物中。你当前 SCSS 中使用的路径：

url("../../../src/assets/fonts/Marcheile-Bold-Condensed.woff")

这种向上穿越多级目录的写法不仅违反 Vite 的模块解析规则，更关键的是：Vite 仅处理 src/ 目录下（或 public/ 目录中）的资源，而不会追踪或打包 ../../../src/ 这类非标准引用路径——它在构建时会被忽略，导致最终 dist/ 中缺失对应文件，浏览器自然 404。

✅ 正确做法是统一将字体文件放入 src/assets/fonts/（推荐），并在 SCSS 中使用相对于 src/ 的路径（即以 /src/ 为基准的相对路径，但更推荐直接用 src/ 下的相对引用）：

/* ✅ 推荐：字体放在 src/assets/fonts/，SCSS 中这样写 */
@font-face {
  font-family: "CustomFont";
  src: url("/src/assets/fonts/Marcheile-Bold-Condensed.woff") format("woff"),
       url("/src/assets/fonts/Marcheile-Bold-Condensed.otf") format("opentype"),
       url("/src/assets/fonts/Marcheile-Bold-Condensed.woff2") format("woff2");
}

⚠️ 注意：此处 /src/... 是 Vite 支持的“绝对路径别名”（基于项目根目录），前提是你的 vite.config.js 未禁用默认行为（Vite 默认支持 / 指向 index.html 所在目录，而 /src/ 可被解析为根目录下的 src/）。但更健壮、更符合惯例的方式是：

✅ 最佳实践：使用 public/ 目录存放无需构建处理的静态资源

将字体文件移至 public/fonts/（项目根目录下新建 public 文件夹）：

社研通

文科研究生的学术加速器

下载

your-project/
├── public/
│   └── fonts/
│       ├── Marcheile-Bold-Condensed.woff
│       ├── Marcheile-Bold-Condensed.otf
│       └── Marcheile-Bold-Condensed.woff2
├── src/
├── vite.config.js
└── package.json

然后在 SCSS 中使用纯静态路径（无前缀 /src/）：

@font-face {
  font-family: "CustomFont";
  src: url("/fonts/Marcheile-Bold-Condensed.woff") format("woff"),
       url("/fonts/Marcheile-Bold-Condensed.otf") format("opentype"),
       url("/fonts/Marcheile-Bold-Condensed.woff2") format("woff2");
}

? 原理：Vite 将 public/ 目录下所有文件原样复制到 dist/ 根目录，因此 /fonts/xxx.woff 在开发（vite dev）和生产（vite preview）中均能被正确访问，且无需构建处理，兼容性最佳。

? 补充配置（可选但推荐）

若你希望自定义 public 目录位置（例如改为 assets/），可在 vite.config.js 中显式声明：

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    minify: false
  },
  // 显式指定 public 目录（默认为 './public'）
  publicDir: 'public' // 或 './assets'
})

? 验证步骤

1. 清理构建产物：rm -rf dist/
2. 重新构建：npm run build
3. 检查 dist/ 目录是否包含 fonts/ 子目录及对应字体文件
4. 启动预览：npm run preview，打开浏览器开发者工具 → Network 标签页，筛选 woff/otf，确认字体请求状态为 200

? 总结

• ❌ 禁止在 SCSS/CSS 中使用 ../../../ 等跨目录相对路径引用资源；
• ✅ 字体/图片等静态资源应置于 src/assets/（需 JS/SCSS 导入）或 public/（直接 URL 访问）；
• ✅ public/ 方案最简单可靠，路径统一为 /xxx，构建后自动映射；
• ✅ 构建后务必检查 dist/ 目录结构，它是运行时的真实资源来源。

遵循以上规范，即可彻底解决 Vite 构建后字体与背景图丢失问题。