React Native 在 iOS 上跑起来功能逻辑都没问题结果一进详情页图片全空白Android 上好好的iOS 就是显示不出来。这种问题我处理过很多次大部分情况不是 React Native 的 bug而是 iOS 平台固有的机制在捣乱。这篇文章我把这些年踩过的坑、排查过的路径、改过的配置整理成一份可以直接照着操作的排查手册覆盖网络图片、本地静态图、Base64 数据图三大类场景每一步都带着原理说明和实操记录。如果你正在被iOS 图片显示不出来折磨先别急着改业务代码花十分钟按下面的思路走一遍大概率能定位到问题。1. 先分清类型所有图片都挂了还是部分图片挂了1.1 拿到问题后的第一反应应该是分类我处理过不少线上反馈很多同学一上来就说iOS 图片不显示但这个描述太宽泛了。你至少要拆成三层来看远程图片https/http 链接能否显示本地打包进 App 的静态图片require 方式能否显示运行时动态生成的数据图片Base64、Blob、文件流能否显示这三类问题在 iOS 上的表现、根因、修复方式完全不同。如果你不做分类上来就改Info.plist大概率白忙活。举个例子我在维护某跨平台系统时收到过一批 iOS 用户反馈个人中心头像全空白。当时我第一反应是 ATS 拦截了 http 请求排查后发现头像链接是 httpsATS 没问题再细看日志发现只有从相册新上传的头像显示不出来老的头像正常。这就把问题缩小到了动态生成的图片这一类最后定位到是本地文件路径拼接错误跟网络请求完全无关。所以接手的第一个动作先把图片来源分类用一个表格记下来图片类型典型场景检查重点网络图片商品图、用户头像、广告 BannerATS、网络权限、URL 有效性、缓存策略本地静态图启动图、Tab 图标、内置占位图require 路径、资源打包、命名规则动态数据图上传后回显、拍照压缩、接口返回 Base64数据格式、编码完整性、内存大小1.2 用三个小实验快速缩小范围分类之后可以在代码里做三个非常快的验证基本十分钟内能锁定问题方向。第一个实验把出问题的图片地址换成一张确定可访问的 https 图片比如一个公开的 CDN 图片地址如果换成之后在 iOS 上能显示说明你的请求通道是通的问题出在原始链接或域名本身如果换了还是空白再看第二步。第二个实验找到项目里一个确定能显示的静态图片比如 App 启动图如果这个也不显示那问题大概率不在单个图片而在整个图片资源加载链路比如 Metro 打包异常、Xcode 工程资源缺失。第三个实验写一个最简单的页面只放一个Image组件指定宽高和固定地址如果在最简环境下能显示、复杂环境不显示说明问题跟页面生命周期、数据传递时序有关而不是图片本身。这三个实验做完你基本能判断出问题属于哪一类接下来就按对应方向深入排查。2. iOS 平台特有的三个大冤种根因2.1 网络图片ATS 传输安全限制ATSApp Transport Security是 iOS 系统从 9.0 开始引入的一项安全机制强制 App 的网络请求必须走 HTTPS并且对加密协议有要求。React Native 在 iOS 上默认继承了这个限制。如果你直接请求一个http://开头的图片地址系统会直接拦截控制台会输出类似这样的信息App Transport Security has blocked a cleartext HTTP (http://) resource load since it is insecure.很多开发者在开发阶段用的是局域网 IP 或者本地 mock 服务比如http://192.168.1.100:8080/xxx.jpgAndroid 上默认不拦截iOS 上默认拦截于是出现了Android 正常、iOS 白屏的经典现象。解决办法是在Info.plist里配置 ATS 例外。但不建议图省事直接全局放开NSAllowsArbitraryLoads虽然开发阶段这样最快但上架审核时容易被拒而且全局放开等于放弃系统安全保护。正确的做法是精确配置域名例外keyNSAppTransportSecurity/key dict keyNSExceptionDomains/key dict keyyour-domain.com/key dict keyNSExceptionAllowsInsecureHTTPLoads/key true/ keyNSIncludesSubdomains/key true/ /dict /dict /dict需要注意一点NSExceptionDomains对 IP 地址是无效的如果你要放行的是192.168.x.x这种局域网 IP必须改用NSAllowsArbitraryLoads或者换用NSAllowsLocalNetworking。iOS 10 之后出了一个NSAllowsLocalNetworking专门用于本地网络请求比全局放开安全得多keyNSAppTransportSecurity/key dict keyNSAllowsLocalNetworking/key true/ /dict如果你的 App 在 iOS 14 上请求局域网地址还涉及本地网络权限NSLocalNetworkUsageDescription这一步也容易漏记得一并加。我之前接过的某个模拟项目就是卡在这个权限上界面没有任何报错图片就是加载不出来加上权限描述文案后立刻恢复。2.2 本地静态图片路径、打包与引用方式本地静态图片在 iOS 上显示不出来通常有三个原因。第一个原因是require路径写错。React Native 里加载本地图片的标准姿势是Image source{require(./assets/images/logo.png)} /注意这个路径是相对于当前 JS 文件所在位置的不是相对于项目根目录。很多同学从网上复制代码路径没改Android 上碰巧存在同名资源能加载iOS 上找不到就开始白屏。iOS 对资源路径的解析比 Android 更严格大小写、后缀名都不能含糊。第二个原因是图片没有被打包进 App。如果图片是从网上下载后丢进项目目录的但没有经过 Metro 的解析构建时可能不会进入 assets 资源包。怎么确认在 Xcode 构建产物里找有没有对应的图片文件或者直接看 Metro 日志里有没有打包该资源的记录。第三个原因是图片命名或格式问题。iOS 对图片格式的兼容性整体不错但还是会有一些奇怪的坑比如某些 webp 图片在 iOS 上显示不出来某些带透明通道的 png 在特定系统版本上渲染异常还有文件名带中文或特殊字符的图片在模拟器上能显示、真机上不显示。我的习惯是统一把图片资源转成 png 或 jpg文件名全部用英文小写加下划线路径中不出现空格。2.3 Base64/二进制数据图片内存与渲染时序陷阱这类问题最隐蔽。Base64 图片在 Android 上显示良好在 iOS 上不显示常见原因有两个。第一Base64 数据不完整。接口返回的 Base64 字符串如果被截断、被转义、或者头信息缺失Image组件就渲染不出来。排查方法是把 Base64 字符串打印出来粘贴到在线的 Base64 转图片工具里如果工具能正常显示说明数据本身没问题如果工具显示不出来问题就在数据源头。第二渲染时序问题。在页面初始化的早期阶段如果图片数据还没有加载完成就把Image组件挂载上去了传入的source可能是空对象或者未定义。此时 iOS 上会静默失败Android 上反而会因为默认行为的不同偶尔能渲染出来。解决方法是给Image加一个条件判断{imageData ? ( Image source{{ uri: data:image/png;base64,${imageData} }} style{{ width: 200, height: 200 }} / ) : ( View style{{ width: 200, height: 200 }} / )}另外值得注意的一点Base64 图片在 iOS 上的内存占用比同尺寸的本地文件图片高不少大图超过 2MB 的 Base64 字符串在低端机型上可能导致内存压力过大被系统强杀。如果图片确实很大建议先压缩再传输不要直接通过data:image方式加载。3. 实操过程从报错到跑通的完整修复记录3.1 修 ATSInfo.plist 到底怎么改最稳妥下面是一段我在实际项目里验证过的 ATS 配置流程。首先在 Xcode 里打开Info.plist以源码方式编辑Open As → Source Code在/dict结束标签之前插入如下内容keyNSAppTransportSecurity/key dict keyNSAllowsLocalNetworking/key true/ keyNSExceptionDomains/key dict keyapi.example.com/key dict keyNSExceptionAllowsInsecureHTTPLoads/key true/ keyNSExceptionMinimumTLSVersion/key stringTLSv1.2/string /dict /dict /dict这段配置表达的意思是允许本地网络的无限制请求同时为api.example.com这个域名单独放行 http 连接。其它域名仍然强制 HTTPS。注意NSExceptionMinimumTLSVersion字段在较新的 iOS 版本上如果写成TLSv1.0或TLSv1.1会被忽略建议直接写TLSv1.2。配置完不要只盯着模拟器看在真机上也必须验证。ATS 在模拟器和真机上的行为基本一致但模拟器可能因为本机代理设置产生干扰真机能更真实地反映问题。如果改完Info.plist发现不生效大概率是没有清干净构建缓存。RN 项目里我习惯这样处理cd ios rm -rf build rm -rf Pods pod install cd .. npx react-native run-ios --reset-cache这段命令会把原生层的配置全部重新生成一遍确保新的Info.plist被正确打入工程。3.2 本地资源手动链接到 Native 工程如果确认图片文件在项目里但 iOS 上还是找不到你需要检查 Xcode 工程里有没有引用这些资源。RN 在大部分情况下会自动处理但某些特殊目录比如动态下载后写入沙箱的图片不会自动打包进 App 资源此时需要手动操作。操作步骤分三步第一步在 Xcode 左侧导航栏选中项目点击根节点在 TARGETS 列表里找到你的 App 目标。第二步选择 Build Phases 选项卡找到 Copy Bundle Resources 区域查看里面是否有目标图片文件。如果没有点击加号从文件选择器里把图片文件添加进去。注意这个文件必须是真实存在于磁盘上的文件不能是文件夹引用。第三步添加之后在代码里引用时路径应该从资源根目录开始写。如果你把图片放在ios/Resources目录下引用方式就是Image source{{ uri: Resources/logo.png }} style{{ width: 100, height: 100 }} /这里的uri是相对 Bundle 根目录的路径不能带file://前缀。很多初学者在这里写成file://...结果 iOS 上无法解析。另外还有一个细节如果你在 Xcode 的 Copy Bundle Resources 里加了图片但构建后资源不生效检查一下图片文件是否真的存在于磁盘Xcode 有时会创建一个无效的红色引用文件实际已移动或删除这种引用在构建时会被静默跳过。3.3 Image 组件动态加载的正确姿势前面提到动态数据图片在 iOS 上容易出问题其实即使是普通的网络图片Image组件的用法也有讲究。最稳的写法是显式指定宽高。iOS 上如果Image没有设置宽高且又没有获取到图片的实际尺寸最终渲染就是零尺寸看起来就像图片不存在。代码示例Image source{{ uri: item.imageUrl }} style{{ width: 120, height: 120, borderRadius: 8 }} resizeModecover onError{(e) console.log(image load error, e.nativeEvent.error)} /这里onError很重要它是排查问题的第一手信息源。iOS 上大多数图片加载失败都会进入onError回调但如果你没监听就只能看到一片空白无从下手。判断图片加载成功还是失败也可以加onLoad/onLoadStart/onLoadEnd来做更细粒度的状态跟踪const [status, setStatus] useState(loading); Image source{{ uri: item.imageUrl }} style{{ width: 120, height: 120 }} onLoadStart{() setStatus(loading)} onLoad{() setStatus(success)} onError{() setStatus(error)} /把状态渲染到页面上就能直观看到当前图片卡在了哪一步。我这里的经验是如果onLoadStart一直不触发说明source本身有问题或组件没有真正挂载如果onLoadStart触发了但onLoad不触发大概率是网络或 ATS 问题如果onLoad触发了但页面还是空白那问题出在渲染层要检查样式、布局、容器层级。4. 常见问题速查表与独家避坑经验4.1 症状-原因-解决方案对照表把实际排查中高频出现的问题整理成一张速查表建议收藏备用症状可能原因解决方案所有网络图片不显示控制台有 ATS 报错ATS 拦截 http 请求Info.plist 配置 NSExceptionDomains 或 NSAllowsLocalNetworking局域网 IP 图片不显示本地网络权限未声明添加 NSLocalNetworkUsageDescription真机授权特定域名不显示其它域名正常域名未加入 ATS 例外在该域名下配置 NSExceptionAllowsInsecureHTTPLoadsrequire 的静态图片不显示require 路径错误或资源未打包检查相对路径Xcode Copy Bundle Resourcesrequire 的图片在模拟器显示、真机不显示文件名含中文或特殊字符重命名为英文小写加下划线Base64 图片不显示数据被截断或格式错误先用在线工具验证 Base64 数据本身图片组件偶发不显示数据加载时序问题加条件判断确保 source 有效后再渲染图片加载后偶发闪退大图内存占用过高图片压缩或改用缩略图地址onError 返回但图片地址正常缓存问题或请求头异常清理缓存或增加随机参数绕过缓存表格列出的每一条我都实际碰到过不是从文档里抄的。尤其是图片加载后偶发闪退这条Android 上很难复现iOS 上因为内存阈值更低一张 5MB 以上的原图直接渲染就可能触发。早期在某图像处理 Demo 项目里我吃了不少这个亏后来统一在服务端做尺寸裁剪问题才算根除。4.2 三个不写进官方文档的土经验第一个经验iOS 模拟器的缓存经常制造假象。模拟器里图片加载正常不代表真机正常反过来模拟器不正常真机却可能正常。原因是模拟器共用 Mac 的网络环境且沙盒缓存行为与真机不完全一致。我的习惯是凡是图片相关的问题一律真机验证模拟器只用来跑流程。第二个经验不要全盘信 React Native 的默认缓存策略。iOS 上Image组件的缓存由系统网络层管理如果服务端返回的 HTTP 头缺少缓存控制字段图片可能被系统强缓存导致用户替换头像后看到的还是旧图。碰到这种问题可以在 URL 后拼接时间戳参数来绕开缓存Image source{{ uri: ${item.imageUrl}?v${Date.now()} }} style{{ width: 80, height: 80 }} /第三个经验遇到图片不显示先去访问一下原图链接。我见过不少案例开发同学调了半天 RN 代码最后发现图片链接本身已经失效。图片链接用浏览器打开能访问才值得继续排查 RN 侧如果浏览器都打不开直接找后端同事解决就行别浪费自己时间。4.3 几个容易被忽略的代码级细节除了上面这些还有几个代码级细节特别容易踩坑。React Native 的Image在 Android 上对source{{ uri: undefined }}的容忍度很高但在 iOS 上可能直接渲染失败或报错。所以从接口拿数据时务必先判断uri字段是否存在const imageUri data data.avatar ? data.avatar : null; Image source{imageUri ? { uri: imageUri } : placeholderImage} style{{ width: 48, height: 48 }} /给source一个兜底值是保平安的最佳实践。另外Image样式里如果不写backgroundColor加载过程中会留白Loading 状态会感觉先闪了一下白屏。这不是 bug但体验很差。加一个浅灰底可以明显改善视觉效果style{{ width: 120, height: 120, backgroundColor: #f0f0f0 }}还有一个关于resizeMode的细节iOS 上默认的缩放行为在某些版本中和 Android 不一致导致同样的图片在两端显示效果不同。我习惯显式声明resizeMode避免依赖默认值。5. 写在最后处理这个问题的通用排查顺序根据我个人的经验在 iOS 上处理 React Native 图片显示问题最有效的排查顺序是这样的第一步看控制台。React Native 在 macOS 上调试时Xcode 控制台和 Metro 终端都会输出错误信息。ATS 拦截、资源加载失败、网络超时都会有明确日志。如果控制台干净问题大概率在业务逻辑或数据层。第二步用浏览器验证图片地址。这一步能快速排除服务端问题。第三步写一个独立的测试页只展示一张图片逐步增加复杂度。这个测试页能帮你确认问题是否与特定页面结构有关。第四步检查 Info.plist 和 Xcode 工程资源。如果前三步都没定位到问题绝大多数情况就卡在这两个配置上。第五步怀疑缓存。清理 App 缓存重启 iOS 设备再试一次。这几步走完不敢说 100% 解决至少能覆盖 iOS 图片问题的 90% 场景。处理这类问题最忌讳的就是凭感觉乱改代码改了一圈也没定位到根因。相反按照分类排查的思路走大部分问题可以在十分钟内锁定方向。如果你手头也遇到了类似问题不妨按这篇文章的顺序走一遍。要是走完还没解决大概率是极端边缘场景建议把你遇到的具体现象、当时的报错日志、图片地址类型拿出来再讨论我会基于实际经验继续帮你拆。