静态资源404排查：从构建输出路径与缓存版本定位故障

🧰 静态资源404先还原完整请求路径

图片、脚本或样式报404时，错误可能来自构建输出路径、部署映射、源站文件缺失、CDN缓存的旧错误对象或浏览器仍持有旧HTML。最有效的起点是记录浏览器发出的精确URL，再沿请求链逐层验证。单看首页状态码正常，不能证明页面依赖资源可达。

🔎 先检查请求和响应证据

在网络面板记录失败URL、状态码、发起页面、重定向链、响应头、缓存状态和错误正文。对比URL的主机、协议、路径大小写、尾斜杠、编码和查询参数。CDN返回的品牌错误页可能掩盖源站真实响应，应查看边缘错误标识与源站日志。curl -I可快速检查头部，但有些源站对HEAD处理不同，验收时要再发实际GET请求。

🏗️ 对照构建产物与部署映射

检查构建配置中的base/public路径、资源输出目录和部署目标。站点部署在子目录时，根绝对路径如/assets/app.js会请求域名根目录，可能绕过应用实际目录。对照HTML引用、构建清单、上传文件路径和源站静态目录映射。Linux文件系统常区分大小写，Logo.png与logo.png在某些开发环境可能表现相同，线上则是不同文件。

若多实例部署，需确认资源已同步到所有可能承接回源的实例，或由共享存储提供。直连某个实例成功不代表负载均衡后的每次请求都成功；结合源站日志中的实例标识定位不一致。

🧊 判断缓存残留还是文件缺失

查看CDN缓存命中状态、对象年龄、ETag以及源站日志。若边缘命中旧404而源站文件现在存在，可按精确URL失效对象后复查；若失效后仍返回404，检查源站实际路径、权限和版本。若HTML自身被缓存为旧版，它可能继续引用旧文件名；此时刷新HTML或发布新版本引用才有效。刷新不会创建缺失文件，也不会纠正构建路径。

✅ 完整验收路径

1. 确认失败资源在构建产物中存在，文件名和大小写一致。
2. 确认部署目标与源站映射正确，并从实际源站路径读取到文件。
3. 通过CDN请求相同URL，检查成功状态、内容类型和响应正文摘要。
4. 重新加载页面，核对浏览器请求的新URL及脚本、样式、图片均成功加载。

清空浏览器缓存只能排除客户端旧状态，不能修复错误URL或服务端缺文件。修复记录应包含失败URL、源站映射、部署版本与CDN验证结果，方便下一次发布快速比对。✅