做 uni-app 多端开发最容易被“小问题”卡住的往往不是复杂逻辑而是像image标签图片加载不出来这种日常小事。我自己踩过不少次浏览器地址栏里图片能打开代码里的src也肉眼检查过没问题可一到小程序或者打包后的 H5 页面就是空白连报错都看不到。这篇文章就把我实战中积累的排查思路和解决办法整理出来从组件渲染原理、路径解析规则到小程序域名限制、H5 防盗链、App 端网络权限帮你从头到尾把这类问题梳理清楚。适合正在被 uni-app 图片问题折磨的前端新手也适合想系统了解image组件行为的老同学。1. 先认清 image 组件的渲染和路径规则不然排查就是瞎猜1.1 多端编译后image 不再是一个纯粹的 img很多开发者容易有一个惯性思维在网页里怎么用img在 uni-app 里就怎么用image。这个思路放在 H5 端没错因为编译后它确实会变成浏览器的img。但在小程序端image会被映射成小程序原生组件在 App 端则可能对应原生视图层级的图片组件。原生组件和网页图片的加载行为、事件回调、样式生效机制都有差异最简单的区别就是网页img不设置宽高时通常按图片原始尺寸展示但在小程序原生组件里经常出现宽高为 0 导致整张图“隐形”的情况。还有一个特别容易踩的点是事件对象。比如error事件H5 端的回调参数是浏览器标准的 Event 对象而小程序端的回调参数通常带detail。如果你在同一个方法里用同一套判断逻辑去读报错信息就可能出现某一端能拿到错误详情、另一端拿不到最后变成“无头冤案”。所以遇到图片不出来我建议先停下来想一下当前你在跑哪个端。同一个src在不同端的解析规则、加载策略、可访问范围都不一样先确认环境的差异比直接改代码高效得多。1.2 src 的路径解析静态路径、动态路径、网络路径要分开看在 uni-app 中src的传值方式直接影响编译器的行为。最容易出现误区的是本地图片路径。比如image src/static/logo.png/image这里/static/logo.png是一个绝对路径编译时会从项目的static根目录下寻找资源多端通用比较推荐。但如果你写成相对路径例如../../static/logo.png在 App 端或某些小程序基础库下解析逻辑可能不一样轻则本地正常发布后找不到重则开发环境就已经裂图。动态绑定是另一个重灾区。:srcitem.img这种赋值方式根本不会经过资源编译运行到什么就是什么。如果item.img是相对路径那它只会按运行时的页面路径去解析很容易 404。本地图片的动态切换最稳的方式是先把图片统一放在static目录下然后在代码里拼绝对路径或者用require/import处理成资源地址再接收。网络图片路径比较简单但要注意必须带完整协议也就是https://开头不能漏掉http:。如果图片地址本身有效浏览器能打开但 uni-app 项目里加载不出来那就得往下面章节的域名限制、跨域策略、防盗链方向排查。2. 图片不显示按这份清单逐项排除2.1 路径写错和动态拼接是“小学生级错误”却最高发先说路径问题。src值里多了空格、少了一个/、大小写不对都会导致加载失败。比如图片文件名是大写的Logo.PNG在 Linux 服务器上你写成了logo.pngH5 开发环境可能没问题但真机或生产环境就会 404。动态拼接地址时最常见的是把后端返回的相对路径直接拼到了src上忘了加域名前缀。我见过有人这么写this.imageUrl item.url // 后端返回的是 /uploads/2024/a.png然后在模板里绑定imageUrl。结果小程序端直接请求/uploads/2024/a.png被当成本地路径当然加载不出来。正确做法是拼接上图片服务的完整域名this.imageUrl https://cdn.example.com item.url更隐蔽的问题是 URL 编码。如果图片文件名带中文、带空格、带特殊符号比如朋友的照片 2024.png直接放进src很可能会被某些端拦截或解码失败。可以用encodeURIComponent先处理文件名部分再组装成完整地址。2.2 小程序平台合法域名开发时好好的真机就白屏如果你在 H5 端能正常显示但在小程序端开发工具里偶尔能出图、真机预览就一片白大概率是“合法域名”问题。小程序原生网络请求对域名有严格限制图片这类资源属于downloadFile范畴。你需要在小程序平台后台把图片所在的域名配置到“downloadFile 合法域名”列表中。平时开发为了方便很多同学会在开发者工具里勾选“不校验合法域名”。这个开关只会影响本地开发环境一旦你编译出预览版或正式版在真机上请求图片时域名不在白名单里请求会被直接拦截。而且更坑的是图片的error事件有时候都不触发看起来就像网络断了非常难排查。配置域名的时候注意三点只能填域名不能带协议头也不能带路径后缀域名必须支持 HTTPS如果用了 CDN 或云存储得填它们实际访问的域名不是业务 API 的域名。如果图片和接口同域那只需要在对应分类如request合法域名里配置一次即可。2.3 H5 端的跨域、防盗链和部署子路径问题H5 端图片不出第一反应应该是打开控制台看 Network。图片多数情况下不受同源策略限制img可以加载跨域图片。但服务器防盗链会干扰很多 CDN 会检查Referer请求头如果你的前端页面域名不在图片服务商的白名单里它会返回 403 或者错误页图片自然展示不出来。这种情况通常是页面里能看到裂图Network 里图片状态码是 403。思路是要么让运维把前端域名加到防盗链白名单要么让后端提供一个图片转发接口把真实图片地址藏起来。另外如果你的代码里想把图片绘制到 canvas 上做海报、压缩图片跨域图片还需要加上crossoriginanonymous并且服务器返回正确的 CORS 响应头否则 canvas 会被污染整段绘图代码白写。还有一个高频问题H5 部署在子路径时/static/开头的图片会全部失效。因为/static/是绝对路径它指向服务器根目录而不是你部署的二级目录。解决办法是配置 H5 端的路由基础路径比如把h5.router.base设置为当前子路径或者发布时统一把静态资源放到服务器根路径的对应位置。如果实在不能改部署结构那就不要写/static/...改成相对路径或者用运行时图片地址。2.4 App 端和 nvue 场景注意 HTTPS 与原生组件差异App 端与 H5、小程序不一样它运行在原生 WebView 或原生渲染引擎里。图片加载不出来最常见的原因有两类第一类是 iOS 的 App Transport SecurityATS限制明文 HTTP 请求默认被拦截。如果图片地址是http://开头在 iOS 上很可能直接加载失败需要把图片服务改成 HTTPS或者按官方要求配置 ATS 例外。第二类是nvue页面的限制。uni-app 的nvue页面使用原生渲染image虽然是组件但内部行为和 Vue 页面不同。比如本地图片路径解析nvue中一定要用绝对路径或原生支持的路径格式动态绑定网路图片时也要注意域名是否被信任。我遇到过一次在vue页面正常、跑到nvue页面图片不显示最后发现是nvue里不能直接用 flex 以外的某些布局模式去容纳图片宽高导致图片实际尺寸直接归零。Android 端相对宽松但如果你使用了本地文件路径例如从相册选择的临时文件必须确保图片文件仍然存在。部分系统清理进程会回收临时目录页面重进之后路径无效图片也会变空白。3. 手把手实操排查从零定位一次 image 加载失败3.1 先写一个能显示错误状态的 image 诊断组件排查图片问题第一步不是去改组件而是把错误信息“逼出来”。我习惯在页面里加一个带状态反馈的image组件类似这样template view image classtest-img :srcimageUrl modeaspectFill loadhandleLoad errorhandleError / text v-ifloading图片加载中.../text text v-iferrorMsg{{ errorMsg }}/text /view /template script export default { data() { return { imageUrl: /static/logo.png, loading: true, errorMsg: } }, methods: { handleLoad() { this.loading false this.errorMsg console.log(image load success) }, handleError(e) { this.loading false this.errorMsg error: JSON.stringify(e.detail || e) console.error(image error, e) } } } /script如果在控制台能看到image error并且打印出了错误详情问题就能缩小范围。如果既没触发error也没触发load说明src可能根本没有发起请求优先检查src值是否为空、拼接是否错误、样式是否把图片宽高压成了 0。3.2 多端验证路径H5 看 Network小程序查域名App 看日志动手排查时要分端走不能一概而论。H5 端最简单打开浏览器的开发者工具切到 Network 面板刷新页面后找图片请求。看三样东西请求状态码、Content-Type 响应头、图片数据预览。如果状态码是 200 但图片还是不出来多半是图片容器样式有问题比如被遮挡、透明、宽高为 0别急着怀疑图片地址。小程序端则要分两种情况开发工具里能显示、真机不能显示优先查合法域名配置开发工具里也不能显示那先看 Network 面板里的请求到底有没有发出去。没有请求检查src值有请求但失败看失败原因是不是域名校验、证书无效、TLS 问题。真机预览时如果你用了调试模式有些工具也会临时跳过域名校验所以正式体验版依然要严谨地配置域名。App 端调试渠道比较分散可以跑在开发工具的真机运行模式里看日志也可以在代码里加 vConsole 之类的调试组件把error的信息显示在页面上。遇到 iOS 端图片加载不了优先怀疑 HTTPS遇到安卓端加载不了优先检查服务器证书和图片地址是否能在公共网络直接访问。3.3 静态图片的正确打开方式用绝对路径和 require很多本地图片不显示本质上是因为图片资源没有被打包进入最终产物。在 uni-app 中static目录下的文件会被原样复制到编译产物中所以本地静态图片尽量放进来然后用绝对路径/static/xxx.png直接引用。但如果你需要根据用户操作切换多张本地图简单的字符串拼接也能用比如const imageName icon_01 this.imageUrl /static/icons/${imageName}.png这种做法要求图片确实存放在static/icons/下。另一种方式是使用require让打包器处理资源适合图片存放在项目非static目录的场景import logoImg from /static/logo.png export default { data() { return { imageUrl: logoImg } } }需要注意的是require的参数一般不能是动态拼接的变量否则打包器找不到具体文件。如果你发现自己无论如何都要动态加载一组本地图片与其变着花样写路径不如把图片放到static下然后用统一的/static/${fileName}.png规则去拼这样反而是跨端兼容性最好的。4. 高频问题速查与独家避坑经验4.1 常见图片加载失败问题速查表下面这张表是我自己整理的高频场景基本覆盖了日常能遇到的大部分情况可以直接对照排查。现象常见原因建议处理方案H5 正常小程序真机不显示域名未配置到 downloadFile 合法域名在小程序平台后台添加图片域名白名单本地开发正常发布后图片失效H5 部署于二级目录绝对路径/static找不到资源配置h5.router.base或改相对路径图片显示为裂图Network 状态 403CDN 防盗链拦截加 Referer 白名单或后端代理图片安卓正常iOS 不显示图片地址是 HTTP被 ATS 拦截将图片地址换成 HTTPS或配置 ATS 例外图片请求 200但页面空白样式问题宽高为 0、被遮挡、透明度为 0检查 image 组件样式和层级动态切换src后不刷新路径拼接错误或 URL 带未编码的中文字符用encodeURIComponent编码参数在 console 打印src值小程序端图片闪烁、懒加载不生效基础库版本过低升级基础库或手动实现图片预加载base64 图片数据太长无法显示图片体积过大超出组件或内存限制大图改用 CDN 地址base64 只适合小图标nvue 页面加载本地图片失败本地路径解析方式不同使用绝对路径 /static或改用 Vue 页面4.2 分享几个我自己踩进去又爬出来的坑先说一个让我印象最深的某次上线前我在小程序开发者工具里关了“不校验合法域名”整个开发周期里图片都正常。等打包成生产版本后几乎全部网络图片都加载不出来用户反馈页面大面积白屏。我一开始以为是 CDN 挂了结果在后台看了半天才发现是新域名忘了加进白名单。那次之后我把“域名白名单”列进了打包前的检查清单每次发布都对着域名列表过一遍。第二个坑是 H5 的子路径问题。当时项目部署在域名的app/目录下本地启动一切正常传到服务器后所有/static/开头的图片全部 404。我排查了很久才发现/static/会从域名根目录找资源但服务器上根本没有根目录下的static。后来通过配置路由基础路径才解决。如果你也遇到“本地能跑、发布后静态资源消失”的诡异问题先别急着改代码看看部署路径和资源路径是否匹配。第三个坑是防盗链。项目里调用了某个图片处理服务的图片开发时浏览器里打开都是好好的放到线上后有些图片就裂了。一开始我以为是网络波动后来发现只要是页面Referer带上我们线上域名服务端就拒绝。联系运维加了白名单之后才稳定。从那以后我碰到第三方图片总是先确认服务商有没有防盗链策略。4.3 顺手把图片加载性能和体验一起优化图片能出来只是底线出来之后还要考虑性能。我的经验是把图片优化方案内置到项目里而不是等出问题再处理。先从源头控制图片体积网络图片尽量使用服务端裁剪或 CDN 缩略图不要直接加载原图。一张 5MB 的原图在手机上加载既慢又占内存换成 800px 宽度的缩略图后肉眼清晰度差距可以忽略加载速度却能快好几倍。image 组件的lazy-load属性也值得开启尤其是在长列表里可以避免用户滑到页面底部之前把所有图片都请求一遍。其次是失败重试。我会给image封装一个小组件记录当前重试次数遇到error时自动重新设置src比如加一个时间戳参数伪装成新地址。因为很多加载失败是偶发性的网络抖动重试一次就可能成功。但要注意重试次数不宜过多否则遇到域名被拦时会陷入无意义的请求循环。如果要支持图片下载、预览这类功能还可以配合 uni-app 的previewImage接口。不过需要提醒一点previewImage在部分端也需要网络图片域名合法否则预览时一样会失败。最好在网络图加载成功后再调用预览接口避免用户点击时还得重新下载。最后说一个个人习惯我会在所有用到网络图片的页面统一引入一个“图片代理函数”它负责把后端返回的相对路径、残缺路径、带特殊字符的路径统一整理成完整可访问的 URL。经过这层处理后大部分“图片突然不显示”的奇葩问题都能在源头被拦截住。多端开发没有银弹但把这些基础规则吃透你的踩坑次数至少能减少一半。
做 uni-app 多端开发最容易被“小问题”卡住的往往不是复杂逻辑而是像image标签图片加载不出来这种日常小事。我自己踩过不少次浏览器地址栏里图片能打开代码里的src也肉眼检查过没问题可一到小程序或者打包后的 H5 页面就是空白连报错都看不到。这篇文章就把我实战中积累的排查思路和解决办法整理出来从组件渲染原理、路径解析规则到小程序域名限制、H5 防盗链、App 端网络权限帮你从头到尾把这类问题梳理清楚。适合正在被 uni-app 图片问题折磨的前端新手也适合想系统了解image组件行为的老同学。1. 先认清 image 组件的渲染和路径规则不然排查就是瞎猜1.1 多端编译后image 不再是一个纯粹的 img很多开发者容易有一个惯性思维在网页里怎么用img在 uni-app 里就怎么用image。这个思路放在 H5 端没错因为编译后它确实会变成浏览器的img。但在小程序端image会被映射成小程序原生组件在 App 端则可能对应原生视图层级的图片组件。原生组件和网页图片的加载行为、事件回调、样式生效机制都有差异最简单的区别就是网页img不设置宽高时通常按图片原始尺寸展示但在小程序原生组件里经常出现宽高为 0 导致整张图“隐形”的情况。还有一个特别容易踩的点是事件对象。比如error事件H5 端的回调参数是浏览器标准的 Event 对象而小程序端的回调参数通常带detail。如果你在同一个方法里用同一套判断逻辑去读报错信息就可能出现某一端能拿到错误详情、另一端拿不到最后变成“无头冤案”。所以遇到图片不出来我建议先停下来想一下当前你在跑哪个端。同一个src在不同端的解析规则、加载策略、可访问范围都不一样先确认环境的差异比直接改代码高效得多。1.2 src 的路径解析静态路径、动态路径、网络路径要分开看在 uni-app 中src的传值方式直接影响编译器的行为。最容易出现误区的是本地图片路径。比如image src/static/logo.png/image这里/static/logo.png是一个绝对路径编译时会从项目的static根目录下寻找资源多端通用比较推荐。但如果你写成相对路径例如../../static/logo.png在 App 端或某些小程序基础库下解析逻辑可能不一样轻则本地正常发布后找不到重则开发环境就已经裂图。动态绑定是另一个重灾区。:srcitem.img这种赋值方式根本不会经过资源编译运行到什么就是什么。如果item.img是相对路径那它只会按运行时的页面路径去解析很容易 404。本地图片的动态切换最稳的方式是先把图片统一放在static目录下然后在代码里拼绝对路径或者用require/import处理成资源地址再接收。网络图片路径比较简单但要注意必须带完整协议也就是https://开头不能漏掉http:。如果图片地址本身有效浏览器能打开但 uni-app 项目里加载不出来那就得往下面章节的域名限制、跨域策略、防盗链方向排查。2. 图片不显示按这份清单逐项排除2.1 路径写错和动态拼接是“小学生级错误”却最高发先说路径问题。src值里多了空格、少了一个/、大小写不对都会导致加载失败。比如图片文件名是大写的Logo.PNG在 Linux 服务器上你写成了logo.pngH5 开发环境可能没问题但真机或生产环境就会 404。动态拼接地址时最常见的是把后端返回的相对路径直接拼到了src上忘了加域名前缀。我见过有人这么写this.imageUrl item.url // 后端返回的是 /uploads/2024/a.png然后在模板里绑定imageUrl。结果小程序端直接请求/uploads/2024/a.png被当成本地路径当然加载不出来。正确做法是拼接上图片服务的完整域名this.imageUrl https://cdn.example.com item.url更隐蔽的问题是 URL 编码。如果图片文件名带中文、带空格、带特殊符号比如朋友的照片 2024.png直接放进src很可能会被某些端拦截或解码失败。可以用encodeURIComponent先处理文件名部分再组装成完整地址。2.2 小程序平台合法域名开发时好好的真机就白屏如果你在 H5 端能正常显示但在小程序端开发工具里偶尔能出图、真机预览就一片白大概率是“合法域名”问题。小程序原生网络请求对域名有严格限制图片这类资源属于downloadFile范畴。你需要在小程序平台后台把图片所在的域名配置到“downloadFile 合法域名”列表中。平时开发为了方便很多同学会在开发者工具里勾选“不校验合法域名”。这个开关只会影响本地开发环境一旦你编译出预览版或正式版在真机上请求图片时域名不在白名单里请求会被直接拦截。而且更坑的是图片的error事件有时候都不触发看起来就像网络断了非常难排查。配置域名的时候注意三点只能填域名不能带协议头也不能带路径后缀域名必须支持 HTTPS如果用了 CDN 或云存储得填它们实际访问的域名不是业务 API 的域名。如果图片和接口同域那只需要在对应分类如request合法域名里配置一次即可。2.3 H5 端的跨域、防盗链和部署子路径问题H5 端图片不出第一反应应该是打开控制台看 Network。图片多数情况下不受同源策略限制img可以加载跨域图片。但服务器防盗链会干扰很多 CDN 会检查Referer请求头如果你的前端页面域名不在图片服务商的白名单里它会返回 403 或者错误页图片自然展示不出来。这种情况通常是页面里能看到裂图Network 里图片状态码是 403。思路是要么让运维把前端域名加到防盗链白名单要么让后端提供一个图片转发接口把真实图片地址藏起来。另外如果你的代码里想把图片绘制到 canvas 上做海报、压缩图片跨域图片还需要加上crossoriginanonymous并且服务器返回正确的 CORS 响应头否则 canvas 会被污染整段绘图代码白写。还有一个高频问题H5 部署在子路径时/static/开头的图片会全部失效。因为/static/是绝对路径它指向服务器根目录而不是你部署的二级目录。解决办法是配置 H5 端的路由基础路径比如把h5.router.base设置为当前子路径或者发布时统一把静态资源放到服务器根路径的对应位置。如果实在不能改部署结构那就不要写/static/...改成相对路径或者用运行时图片地址。2.4 App 端和 nvue 场景注意 HTTPS 与原生组件差异App 端与 H5、小程序不一样它运行在原生 WebView 或原生渲染引擎里。图片加载不出来最常见的原因有两类第一类是 iOS 的 App Transport SecurityATS限制明文 HTTP 请求默认被拦截。如果图片地址是http://开头在 iOS 上很可能直接加载失败需要把图片服务改成 HTTPS或者按官方要求配置 ATS 例外。第二类是nvue页面的限制。uni-app 的nvue页面使用原生渲染image虽然是组件但内部行为和 Vue 页面不同。比如本地图片路径解析nvue中一定要用绝对路径或原生支持的路径格式动态绑定网路图片时也要注意域名是否被信任。我遇到过一次在vue页面正常、跑到nvue页面图片不显示最后发现是nvue里不能直接用 flex 以外的某些布局模式去容纳图片宽高导致图片实际尺寸直接归零。Android 端相对宽松但如果你使用了本地文件路径例如从相册选择的临时文件必须确保图片文件仍然存在。部分系统清理进程会回收临时目录页面重进之后路径无效图片也会变空白。3. 手把手实操排查从零定位一次 image 加载失败3.1 先写一个能显示错误状态的 image 诊断组件排查图片问题第一步不是去改组件而是把错误信息“逼出来”。我习惯在页面里加一个带状态反馈的image组件类似这样template view image classtest-img :srcimageUrl modeaspectFill loadhandleLoad errorhandleError / text v-ifloading图片加载中.../text text v-iferrorMsg{{ errorMsg }}/text /view /template script export default { data() { return { imageUrl: /static/logo.png, loading: true, errorMsg: } }, methods: { handleLoad() { this.loading false this.errorMsg console.log(image load success) }, handleError(e) { this.loading false this.errorMsg error: JSON.stringify(e.detail || e) console.error(image error, e) } } } /script如果在控制台能看到image error并且打印出了错误详情问题就能缩小范围。如果既没触发error也没触发load说明src可能根本没有发起请求优先检查src值是否为空、拼接是否错误、样式是否把图片宽高压成了 0。3.2 多端验证路径H5 看 Network小程序查域名App 看日志动手排查时要分端走不能一概而论。H5 端最简单打开浏览器的开发者工具切到 Network 面板刷新页面后找图片请求。看三样东西请求状态码、Content-Type 响应头、图片数据预览。如果状态码是 200 但图片还是不出来多半是图片容器样式有问题比如被遮挡、透明、宽高为 0别急着怀疑图片地址。小程序端则要分两种情况开发工具里能显示、真机不能显示优先查合法域名配置开发工具里也不能显示那先看 Network 面板里的请求到底有没有发出去。没有请求检查src值有请求但失败看失败原因是不是域名校验、证书无效、TLS 问题。真机预览时如果你用了调试模式有些工具也会临时跳过域名校验所以正式体验版依然要严谨地配置域名。App 端调试渠道比较分散可以跑在开发工具的真机运行模式里看日志也可以在代码里加 vConsole 之类的调试组件把error的信息显示在页面上。遇到 iOS 端图片加载不了优先怀疑 HTTPS遇到安卓端加载不了优先检查服务器证书和图片地址是否能在公共网络直接访问。3.3 静态图片的正确打开方式用绝对路径和 require很多本地图片不显示本质上是因为图片资源没有被打包进入最终产物。在 uni-app 中static目录下的文件会被原样复制到编译产物中所以本地静态图片尽量放进来然后用绝对路径/static/xxx.png直接引用。但如果你需要根据用户操作切换多张本地图简单的字符串拼接也能用比如const imageName icon_01 this.imageUrl /static/icons/${imageName}.png这种做法要求图片确实存放在static/icons/下。另一种方式是使用require让打包器处理资源适合图片存放在项目非static目录的场景import logoImg from /static/logo.png export default { data() { return { imageUrl: logoImg } } }需要注意的是require的参数一般不能是动态拼接的变量否则打包器找不到具体文件。如果你发现自己无论如何都要动态加载一组本地图片与其变着花样写路径不如把图片放到static下然后用统一的/static/${fileName}.png规则去拼这样反而是跨端兼容性最好的。4. 高频问题速查与独家避坑经验4.1 常见图片加载失败问题速查表下面这张表是我自己整理的高频场景基本覆盖了日常能遇到的大部分情况可以直接对照排查。现象常见原因建议处理方案H5 正常小程序真机不显示域名未配置到 downloadFile 合法域名在小程序平台后台添加图片域名白名单本地开发正常发布后图片失效H5 部署于二级目录绝对路径/static找不到资源配置h5.router.base或改相对路径图片显示为裂图Network 状态 403CDN 防盗链拦截加 Referer 白名单或后端代理图片安卓正常iOS 不显示图片地址是 HTTP被 ATS 拦截将图片地址换成 HTTPS或配置 ATS 例外图片请求 200但页面空白样式问题宽高为 0、被遮挡、透明度为 0检查 image 组件样式和层级动态切换src后不刷新路径拼接错误或 URL 带未编码的中文字符用encodeURIComponent编码参数在 console 打印src值小程序端图片闪烁、懒加载不生效基础库版本过低升级基础库或手动实现图片预加载base64 图片数据太长无法显示图片体积过大超出组件或内存限制大图改用 CDN 地址base64 只适合小图标nvue 页面加载本地图片失败本地路径解析方式不同使用绝对路径 /static或改用 Vue 页面4.2 分享几个我自己踩进去又爬出来的坑先说一个让我印象最深的某次上线前我在小程序开发者工具里关了“不校验合法域名”整个开发周期里图片都正常。等打包成生产版本后几乎全部网络图片都加载不出来用户反馈页面大面积白屏。我一开始以为是 CDN 挂了结果在后台看了半天才发现是新域名忘了加进白名单。那次之后我把“域名白名单”列进了打包前的检查清单每次发布都对着域名列表过一遍。第二个坑是 H5 的子路径问题。当时项目部署在域名的app/目录下本地启动一切正常传到服务器后所有/static/开头的图片全部 404。我排查了很久才发现/static/会从域名根目录找资源但服务器上根本没有根目录下的static。后来通过配置路由基础路径才解决。如果你也遇到“本地能跑、发布后静态资源消失”的诡异问题先别急着改代码看看部署路径和资源路径是否匹配。第三个坑是防盗链。项目里调用了某个图片处理服务的图片开发时浏览器里打开都是好好的放到线上后有些图片就裂了。一开始我以为是网络波动后来发现只要是页面Referer带上我们线上域名服务端就拒绝。联系运维加了白名单之后才稳定。从那以后我碰到第三方图片总是先确认服务商有没有防盗链策略。4.3 顺手把图片加载性能和体验一起优化图片能出来只是底线出来之后还要考虑性能。我的经验是把图片优化方案内置到项目里而不是等出问题再处理。先从源头控制图片体积网络图片尽量使用服务端裁剪或 CDN 缩略图不要直接加载原图。一张 5MB 的原图在手机上加载既慢又占内存换成 800px 宽度的缩略图后肉眼清晰度差距可以忽略加载速度却能快好几倍。image 组件的lazy-load属性也值得开启尤其是在长列表里可以避免用户滑到页面底部之前把所有图片都请求一遍。其次是失败重试。我会给image封装一个小组件记录当前重试次数遇到error时自动重新设置src比如加一个时间戳参数伪装成新地址。因为很多加载失败是偶发性的网络抖动重试一次就可能成功。但要注意重试次数不宜过多否则遇到域名被拦时会陷入无意义的请求循环。如果要支持图片下载、预览这类功能还可以配合 uni-app 的previewImage接口。不过需要提醒一点previewImage在部分端也需要网络图片域名合法否则预览时一样会失败。最好在网络图加载成功后再调用预览接口避免用户点击时还得重新下载。最后说一个个人习惯我会在所有用到网络图片的页面统一引入一个“图片代理函数”它负责把后端返回的相对路径、残缺路径、带特殊字符的路径统一整理成完整可访问的 URL。经过这层处理后大部分“图片突然不显示”的奇葩问题都能在源头被拦截住。多端开发没有银弹但把这些基础规则吃透你的踩坑次数至少能减少一半。
