企业官网建设流程全解析

做 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 端或某些小程序基础库下，解析逻辑可能不一样，轻则本地正常发布后找不到，重则开发环境就已经裂图。

动态绑定是另一个重灾区。:src="item.img"这种赋值方式根本不会经过资源编译，运行到什么就是什么。如果item.img是相对路径，那它只会按运行时的页面路径去解析，很容易 404。本地图片的动态切换，最稳的方式是先把图片统一放在static目录下，然后在代码里拼绝对路径，或者用require/import处理成资源地址再接收。

网络图片路径比较简单，但要注意必须带完整协议，也就是https://开头，不能漏掉http:。如果图片地址本身有效，浏览器能打开，但 uni-app 项目里加载不出来，那就得往下面章节的域名限制、跨域策略、防盗链方向排查。

2. 图片不显示：按这份清单逐项排除

2.1 路径写错和动态拼接是“小学生级错误”，却最高发

先说路径问题。src值里多了空格、少了一个/、大小写不对，都会导致加载失败。比如图片文件名是大写的Logo.PNG，在 Linux 服务器上你写成了logo.png，H5 开发环境可能没问题，但真机或生产环境就会 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 上做海报、压缩图片，跨域图片还需要加上crossorigin="anonymous"，并且服务器返回正确的 CORS 响应头，否则 canvas 会被污染，整段绘图代码白写。

还有一个高频问题：H5 部署在子路径时，/static/开头的图片会全部失效。因为/static/是绝对路径，它指向服务器根目录，而不是你部署的二级目录。解决办法是配置 H5 端的路由基础路径，比如把h5.router.base设置为当前子路径，或者发布时统一把静态资源放到服务器根路径的对应位置。如果实在不能改部署结构，那就不要写/static/...，改成相对路径或者用运行时图片地址。

2.4 App 端和 nvue 场景，注意 HTTPS 与原生组件差异

App 端与 H5、小程序不一样，它运行在原生 WebView 或原生渲染引擎里。图片加载不出来最常见的原因有两类：第一类是 iOS 的 App Transport Security（ATS）限制，明文 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 class="test-img" :src="imageUrl" mode="aspectFill" @load="handleLoad" @error="handleError" /> <text v-if="loading">图片加载中...</text> <text v-if="errorMsg">{{ 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 常见图片加载失败问题速查表

下面这张表是我自己整理的高频场景，基本覆盖了日常能遇到的大部分情况，可以直接对照排查。

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。经过这层处理后，大部分“图片突然不显示”的奇葩问题都能在源头被拦截住。多端开发没有银弹，但把这些基础规则吃透，你的踩坑次数至少能减少一半。