Vue 3 + Vite构建报错：图片与字体路径无法找到求助

一、标准化项目结构 #

先梳理清晰的资源存放规则，避免路径混乱：

• src/
  • assets/
    • images/：存放组件内、样式中引用的图片资源
    • fonts/：存放自定义字体、Bootstrap图标字体等
    • styles/：存放Sass主文件、自定义样式
• public/：存放无需Vite处理的全局静态资源（如favicon、超大背景图）

二、不同场景的资源引用方式 #

1. Vue组件内引用图片（优先用assets） #

两种靠谱写法，Vite会自动处理资源哈希和路径映射：

<template>
  <!-- 方式1：直接写相对路径 -->
  <img src="../assets/images/avatar.png" alt="用户头像">
  <!-- 方式2：导入后绑定 -->
  <img :src="logoImg" alt="logo">
</template>

<script setup>
import logoImg from '../assets/images/logo.png'
</script>

2. Sass/Bootstrap中引用资源 #

注意路径是相对于当前SCSS文件的层级：

// 假设当前文件是src/assets/styles/main.scss
// 引用同级目录下images里的背景图
.bg-home {
  background-image: url('../images/home-bg.jpg');
}

// 自定义字体引用
@font-face {
  font-family: 'MyFont';
  src: url('../fonts/my-font.woff2') format('woff2');
}

// 覆盖Bootstrap图标路径（导入Bootstrap前设置）
$icon-font-path: '../assets/fonts/bootstrap-icons/';
@import 'bootstrap/scss/bootstrap';

3. Public文件夹资源引用 #

放在public里的资源，必须以/开头（对应项目根路径）：

<!-- 对应public/images/banner.jpg -->
<img src="/images/banner.jpg" alt="首页横幅">

构建时Vite会把public内的资源原封不动复制到dist根目录，绝对路径能避免路径错误。

三、Vite配置调整（解决部署路径问题） #

如果部署在非根目录（如https://xxx.com/my-app/），在vite.config.js中设置base：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  // 部署到子路径就写对应路径，比如'/my-app/'；任意路径用'./'
  base: './'
})

四、常见错误排查 #

• 检查路径拼写，尤其是大小写（Linux服务器区分大小写）
• 确认assets内资源没被.gitignore误排除
• 构建后查看dist文件夹结构，验证资源是否正确打包、路径是否匹配
• SCSS中嵌套层级多的话，避免用../过多导致的路径错误，可尝试用~@/assets/xxx（需配置@别名）

内容的提问来源于stack exchange，提问作者Sargentogato