为什么iOS打包IPA的运行表现与Xcode直接运行不一致？

现象：Xcode直连运行模拟器、真机时所有图片加载正常，导出IPA安装后部分图片无法展示，清理项目、重新构建后问题依旧。

按以下优先级逐一排查：

• 先核对图片命名规则
  禁止在图片文件名里使用中文、空格、特殊符号，除了系统要求的@2x/@3x倍率后缀外不要加自定义后缀；不要存仅大小写有差异的同名图片（比如Setting.png和setting.png）。Debug模式下Xcode和Metro对文件名容错度高，Release打包时资源压缩、去重逻辑会直接过滤不符合规则、判定为重复的资源。
• 检查资源引入逻辑
  不要用字符串拼接的方式写require引入路径，比如require(./icon/${name}.png)这种写法，Debug时Metro会遍历全量目录做资源映射可以正常加载，Release打包时静态分析无法识别动态拼接的路径，对应图片根本不会被打进包内。
  如果是放在Xcode Images.xcassets里的原生资源，点开图片文件检查右侧「Target Membership」栏，确认主应用Target已经勾选——很多项目Debug配置默认带了Target关联，Release配置漏选就会出现资源缺失。
• 核对RN打包脚本配置
  Archive打包前先手动执行一次bundle打包命令，确认--assets-dest参数指向的资源输出路径正确，执行完成后先去输出目录里核对，确认缺失的图片已经被导出到assets目录下。
  0.60+版本如果开启了Hermes引擎，先删除ios/build目录、~/Library/Developer/Xcode/DerivedData下对应项目的所有缓存文件，再重新执行bundle命令后走Archive流程，避免Hermes字节码缓存导致旧的资源映射残留。
• 校验图片本身格式合法性
  不要把JPG格式的图片强行改后缀为PNG，Debug模式下系统会自动识别文件头解码，Release模式下iOS会严格按后缀匹配解码器，格式不匹配会直接加载失败。
  检查异常图片的分辨率，非纹理类图片宽高不要超过4096px，iOS硬解码对超大幅图片有内存阈值限制，Release模式下会直接渲染失败，Debug模式的调试容错机制不会触发这个限制。

快速定位技巧 #

把导出的IPA文件后缀改为.zip后解压，打开Payload文件夹下的.app包，搜索缺失的图片文件名：如果包里根本找不到对应文件，就是打包环节资源漏入；如果文件存在但仍无法显示，优先排查命名、格式、路径映射问题。

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