React Native误将本地图片识别为模块，加载失败求助

架构老林

2026-5-28

排查React Native本地图片加载失败的几个关键细节

兄弟我太懂这种严格按文档操作却死活跑不通的崩溃感了！我之前也踩过React Native本地图片的各种坑，给你列几个容易忽略的排查点，说不定能解决你的问题：

文件名与命名规范问题
你的图片名3D-home@2x.jpg里包含了@和-这类特殊字符，而且手动指定@2x的写法其实不符合React Native的图册逻辑。React Native会自动根据设备分辨率匹配对应后缀的图片（比如@2x、@3x），你只需要把不同分辨率的图片放在同一目录，统一用基础名命名（比如3d_home.jpg、3d_home@2x.jpg、3d_home@3x.jpg），然后代码里直接写require('./3d_home.jpg')即可，不用手动加@2x。另外注意文件名大小写，Android系统对大小写是严格区分的，比如文件实际是3D-Home.jpg但代码里写3D-home.jpg就会加载失败。
路径与资源引用的准确性
确认图片路径是相对于当前JS文件的正确相对路径：如果JS文件在src/screens/Home.js，图片放在同一目录，./是正确的；如果图片放在项目根目录，应该用../（比如../3d_home.jpg）。另外，如果你尝试用Images.xcassets，要确保：
1. Xcode项目中已经将Images.xcassets添加到目标项目（勾选Target Membership）；
2. 图片是放在xcassets的Image Set中（不是直接拖进文件夹）；
3. 引用时用require('./Images.xcassets/你的ImageSet名称')，而不是旧的image!语法。
彻底清理缓存与构建文件
你已经做了缓存清理，但可以试试更彻底的操作：
1. 删除项目根目录的node_modules文件夹，重新执行yarn install；
2. 打开Xcode，删除项目的Derived Data（路径：~/Library/Developer/Xcode/DerivedData，找到对应项目文件夹删除）；
3. 执行Command+Shift+K清理Xcode构建缓存，然后重新构建项目；
4. 再次执行yarn start --reset-cache启动Metro。
排除样式与组件本身的问题
你的Image用了绝对定位和100%宽高，有可能是父容器没有设置宽高导致图片无法显示（你误以为是加载失败）。可以先给Image临时添加backgroundColor: 'red'，如果能看到红色块，说明组件本身是渲染了的，问题可能出在图片加载或者样式适配上。另外确认你正确导入了React Native的Image组件：
```
import { Image } from 'react-native';
```
不要误导入了第三方库的Image组件。
测试最小可复现案例
新建一个极简的测试页面，比如：
```
import React from 'react';
import { View, Image } from 'react-native';

const TestImagePage = () => {
  return (
    <View style={{ flex: 1 }}>
      <Image source={require('./test.jpg')} style={{ width: 200, height: 200 }} />
    </View>
  );
};

export default TestImagePage;
```
把一张命名简单的图片（比如test.jpg）放在同一目录，导航到这个页面测试。如果这个能正常加载，说明原页面的问题可能出在其他逻辑上；如果还是失败，那大概率是项目配置的问题。

希望这些方法能帮你解决问题，实在不行可以检查一下React Native的版本，某些旧版本确实存在本地图片加载的bug，升级到稳定版可能会解决。

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