React Native iOS部署后本地Assets图片不显示问题求助

1. 资源引用规则排查 #

• 检查require写法：RN 0.63版本不支持动态拼接本地图片路径，所有路径必须为静态字符串，禁止使用require(`./assets/${imgName}.png`)这类模板字符串拼接写法，必须写全静态路径。
• 检查命名一致性：iOS真机资源加载严格区分大小写，确认代码中引用的文件名、后缀和实际存储的文件完全匹配，不要出现代码写home_icon.png实际文件名为Home_Icon.PNG的情况；引用时不要手动加@2x/@3x倍率后缀，RN会自动根据屏幕参数匹配对应倍率资源。
• 检查文件格式合法性：不要直接修改文件后缀伪造图片格式（比如把jpg后缀改成png），Xcode编译阶段会校验图片头信息，格式不匹配的资源会被直接剔除出安装包。

2. Xcode资源挂载配置排查（0.63版本高发问题） #

• 打开iOS目录下的.xcworkspace文件，找到项目中的资源文件：如果是存放在Images.xcassets里的图片，确认资源已被导入到目录中；如果是存放在自定义文件夹的图片，选中文件后查看右侧File Inspector面板，确认Target Membership下已勾选应用主Target。
• 进入项目配置的Build Phases - Copy Bundle Resources列表，确认用到的图片文件/资源文件夹在列表内，缺失的话点击底部加号手动添加。
• 自定义资源文件夹要选择Create folder references引用类型（显示为蓝色文件夹图标），不要选Create groups（黄色文件夹图标），后者不会将目录下的层级资源完整拷贝到安装包中。

3. 缓存清理操作（Xcode13.4.1偶现缓存异常） #

• 先清理RN侧缓存，在项目根目录执行以下命令：

watchman watch-del-all
rm -rf node_modules && yarn install # 使用npm的话替换为npm install
rm -rf /tmp/metro-*

• 清理Xcode侧缓存：打开Xcode按Cmd + Shift + K清空构建产物，再按Cmd + Option + Shift + K清空全局构建缓存，同时手动删除iOS目录下的build文件夹。
• 回到iOS目录执行pod install后，重新编译运行或打包测试。

4. 特殊场景排查 #

• 如果仅Release包出现图片不显示、Debug模式正常：检查Build Settings下的Optimization Level配置，0.63版本在Xcode13下选Fastest, Smallest [-Os]偶现资源被错误裁剪，可临时调整为None [-O0]验证问题。
• 如果是自定义原生组件加载的图片：检查原生端取路径逻辑，不要写死沙盒路径，要通过[[NSBundle mainBundle] pathForResource:ofType:]方法获取安装包内的正式资源路径。

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