在 Vite 项目中，public 文件夹内的资源（如图片、图标、JSON 等）不会参与构建处理，而是直接映射到应用根路径；因此必须使用以 / 开头的绝对路径（如 /images/image01.jpg）引用，而非 ./ 相对路径或 /public/... 冗余路径。
在 vite 项目中，public 文件夹内的资源（如图片、图标、json 等）不会参与构建处理，而是直接映射到应用根路径；因此必须使用以 `/` 开头的绝对路径（如 `/images/image01.jpg`）引用，而非 `./` 相对路径或 `/public/...` 冗余路径。
✅ 正确做法：统一使用根绝对路径
Vite 将 public/ 目录下的所有内容自动挂载到开发服务器和生产构建的根路径（/）下。这意味着：
- 若你在
public/images/image01.jpg存放图片， - 则在 HTML、CSS 或 JS 中应始终写作
/images/image01.jpg—— 不加public前缀，也不用./或../。
✅ 正确示例：
<!-- a.html --> @@##@@
/* 在 CSS 中（如 style.css 或 <style> 标签内） */
.hero-bg {
background-image: url('/images/hero-bg.png');
}</style>
// 在 JavaScript 中动态设置 const img = new Image(); img.src = '/images/logo.svg'; // ✅ 绝对路径，浏览器可直接解析 document.body.appendChild(img);
❌ 错误写法及原因：
| 写法 | 问题 |
|------|------|
| <img src="/images/image01.jpg" loading="lazy" alt="示例图"> | Vite 明确警告：Files in the public directory are served at the root path —— /public 是物理目录名，不是 URL 路径的一部分，添加后会导致 404（尤其在生产环境） |
| <img src="/public/images/image01.jpg"> | 相对路径依赖当前 HTML 所在位置；若 a.html 被路由重写（如 /about/a.html）或部署在子路径（如 /app/），路径将失效 |
| <img src="./images/image01.jpg"> | 同样受上下文路径影响，不可靠，且开发与生产行为不一致 |
⚠️ 特别注意：你的 vite.config.js 中 base: "./" 是关键隐患
你当前配置了：
base: "./", root: "./src",
⚠️ 这会导致严重路径冲突：
-
base: "./"表示所有资源 URL 以相对路径（./）为前缀，即生成的<script src="./assets/index.abc123.js"></script>； - 但 public 资源必须通过
/根路径访问（Vite 内部机制强制要求），此时base: "./"会破坏 public 资源的解析逻辑，导致/images/xxx.jpg在某些场景下无法加载（尤其配合自定义root时）。
✅ 推荐修正为：
// vite.config.js（精简关键项）
import { defineConfig } from 'vite';
export default defineConfig({
// ✅ 改为显式根路径（开发与生产一致）
base: '/', // 或部署在子路径时设为 '/my-app/'
// ✅ root 应保持默认（'.'），除非你有强理由移动源码根
// root: './', // ← 默认值，无需显式声明；若设为 './src'，则 public 必须也在 ./src/public —— 但你实际放在项目根！
// 其他配置保持不变...
});
? 验证路径结构前提：确保你的 public/images/image01.jpg 确实位于项目根目录下的 public/ 文件夹中（即与 vite.config.js、package.json 同级），而非嵌套在 src/public/ 或其他位置。
? 补充：何时该用 public/？何时该用 src/assets/？
| 场景 | 推荐位置 | 引用方式 | 说明 |
|---|---|---|---|
| 网站 favicon.ico、robots.txt、manifest.json、第三方 JS 备份（如 jQuery.min.js） | public/ |
/favicon.ico |
不需构建处理，保留原始文件名与路径，支持 CDN 直链 |
| 组件专属图片、SVG 图标、需压缩/转 Base64/哈希命名的资源 | src/assets/ |
import logo from '@/assets/logo.png' 或 new URL('@/assets/icon.svg', import.meta.url).href
|
参与构建优化，享受类型检查、热更新、按需加载等能力 |
? 小技巧：为避免硬编码路径，可封装一个安全的资源工具函数（适用于
public资源）：// src/utils/public-assets.ts export const publicAsset = (path: string) => { if (!path.startsWith('/')) throw new Error('Public asset path must start with "/"'); return path; }; // 使用 const logoUrl = publicAsset('/images/logo-dark.png');
✅ 最终检查清单
- [ ] 图片真实路径为：
<project-root>/public/images/image01.jpg</project-root> - [ ] HTML 中引用为：
<img src="../images/image01.jpg">（无public，无./） - [ ]
vite.config.js中base设为'/'（或明确子路径如'/my-app/'），移除root: './src'（除非你已将public移至src/下） - [ ] 构建后检查
dist/目录：dist/images/image01.jpg应存在，且 HTML 中<img src="/images/image01.jpg">可正常请求
遵循以上规范，即可彻底解决 “图片 404”、“开发正常但生产失效”、“Vite 警告冗余路径” 等典型问题，实现跨环境稳定、可维护的静态资源管理。
