React开发过程中图片加载损坏显示异常该如何解决

路径类问题排查 #

• 静态资源存放位置校验：存放在public目录的图片，引用路径直接写/资源相对public的路径，无需加public前缀；存放在src目录的图片，必须通过import引入后赋值给src属性，不可直接在标签内写相对路径
• 动态路径校验：如果路径是动态拼接生成的，先打印最终拼接结果确认无拼写错误、多余/缺失斜杠、多余空格；vite项目动态引入src下资源需使用new URL('./图片相对路径', import.meta.url).href生成正确路径
• 大小写校验：Linux部署环境对路径大小写敏感，需确认代码里的路径拼写和实际文件路径大小写完全一致，避免本地Windows/Mac运行正常、线上404的问题
• 网络请求校验：打开浏览器控制台「网络」面板，筛选Img类型请求，确认图片实际请求地址和预期一致，返回状态码为200

资源与构建配置排查 #

• 图片本身校验：本地直接打开图片文件，确认资源本身没有损坏
• 格式兼容性校验：如果使用webp、avif等小众格式，确认浏览器版本支持对应格式，或配置了通用格式回退方案
• 构建工具配置校验：检查webpack/vite的图片处理规则，确认url-loader/asset parser的大小阈值配置合理，小图片转base64时无转码错误；确认对应图片格式的loader配置正确

部署与权限排查 #

• 直接访问校验：复制图片完整请求URL直接在浏览器地址栏打开，确认资源本身可以正常访问
• 防盗链/跨域校验：如果图片存放在CDN/对象存储服务，确认防盗链白名单包含当前站点域名，跨域配置允许当前站点访问
• 资源权限校验：确认部署环境下图片资源的文件权限正常，没有出现403无权限访问的问题

框架与语法排查 #

• 语法错误校验：确认img标签src属性绑定正确，变量引用使用src={变量名}而非src="变量名"
• 框架组件校验：如果使用Next.js、Remix等框架内置的Image组件，确认远程图片域名已添加到框架配置的允许列表，必填的宽高属性已正确配置
• 全局逻辑校验：排查是否有全局样式、JS逻辑意外修改了img标签的src属性或覆盖了图片显示内容

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