图片路径对了还404？前端资源加载避坑指南

在前端开发中，新手几乎都会踩过一个坑：本地开发时图片显示正常，但项目构建并部署到服务器后，图片却加载失败，直接报出 404 Not Found 错误。

明明路径写得“没错”，为什么浏览器就是找不到文件？其实，图片加载不出来，核心原因通常归结为两点：路径是否正确以及文件是否真实存在。

本文将深入解析导致这一问题的常见场景，帮助你彻底理清图片从哪来、浏览器为何找不到。

1. 本地与生产环境的路径差异

在本地开发环境中，我们往往直接使用相对路径或绝对路径引用图片，例如 Amiga logo.png。此时，由于开发服务器（Dev Server）通常直接映射源码目录，图片可以正常访问。

然而，一旦项目进入**构建（Build）**阶段，目录结构会发生显著变化。构建工具会将源码重新打包、压缩并输出到新的目录中。原本在本地有效的路径，在构建后的生产环境中可能已经失效。因此，不能简单地将本地路径直接复制到生产环境配置中。

2. 放错目录：Public 与 src 的区别

大多数现代前端框架（如 React、Vue 等）对静态资源的管理有严格区分，图片放置的位置直接决定了其引用方式：

• Public 目录：

  • 行为：放置在 public 文件夹中的图片，在构建时会原样复制到输出目录的根目录下。
  • 引用方式：可以直接通过根路径访问，例如 <img src="/logo.png" />。
  • 适用场景：不需要经过构建工具处理、路径固定的静态资源。

• src 目录：

  • 行为：放置在 src 文件夹中的图片，必须通过 import 或模块引入的方式加载。构建工具（如 Webpack、Vite）会处理这些资源，生成带有哈希值的文件名或特定的 URL。
  • 引用方式：import logo from './logo.png'; 然后在组件中使用变量。
  • 风险：如果将本应放在 public 的图片误放在 src 中且未正确引入，或者反之，打包后构建工具可能无法正确解析路径，导致资源丢失。

3. 检查构建产物：文件是否真的打包进去了？

路径配置正确，但文件本身可能并未被打包进最终产物。这是一个极易被忽略的检查步骤。

以 Vite 为例，运行 npm run build 后，请检查生成的 dist 文件夹：

1. 进入 dist 目录。
2. 查找对应的图片文件是否存在。
3. 如果图片文件根本不在 dist 中，说明构建工具没有将其纳入打包范围。

结论：如果文件没有被打包进去，无论你在代码中如何配置路径，浏览器都无法找到该文件，必然报 404 错误。

4. 缓存陷阱：浏览器与 CDN

有时候，图片路径和文件本身都没有问题，但浏览器依然显示旧图或报错，这通常是缓存在作祟。

• 浏览器缓存：

  • 当你更新了图片文件但文件名未变时，浏览器可能仍从本地缓存中读取旧文件。
  • 解决方法：尝试强制刷新（Ctrl + F5 或 Cmd + Shift + R），或清除浏览器缓存。

• CDN 缓存：

  • 如果项目部署在 CDN 上，CDN 节点会有缓存周期。即使源站文件已更新，CDN 节点可能仍返回旧的缓存内容。
  • 解决方法：检查 CDN 配置，手动刷新缓存或等待缓存过期。注意，CDN 缓存更新并非实时生效，需预留一定时间。

总结：排查 404 的标准流程

当遇到“路径对了还 404”的问题时，建议按以下顺序排查：

1. 确认文件存在：检查构建产物目录（如 dist），确认图片文件是否被成功打包。
2. 检查引用方式：确认图片是放在 public 还是 src，并采用对应的引用方式（直接路径 vs import）。
3. 验证路径逻辑：确保构建后的路径映射正确，没有因目录结构变化导致的路径失效。
4. 清除缓存：强制刷新浏览器，并检查 CDN 缓存状态。

通过系统化地排查以上环节，你可以快速定位并解决前端图片加载失败的问题。