React Native项目添加图片指定路径后无法显示问题排查

React（Web）项目常见原因 #

• 路径匹配问题
  • 相对路径层级计算错误，比如多写或少写../导致找不到文件
  • 文件名大小写不匹配，Linux/macOS系统区分大小写，实际文件HeaderLogo.png和代码中headerlogo.png会被视为不同路径
  • 使用未配置别名的绝对路径，React web项目默认不识别根目录绝对路径，需通过webpack配置resolve.alias才能使用
• 资源打包配置问题
  • 未配置图片资源处理规则：React 17+需启用webpack的asset modules（如type: 'asset/resource'），旧版本需配置file-loader/url-loader，否则打包时图片不会被正确输出
  • publicPath配置错误，导致打包后图片的引用路径和实际输出路径不匹配
• 文件自身问题
  • 图片文件损坏，无法被浏览器正常解析渲染
  • 使用了浏览器不支持的罕见图片格式
• 组件使用错误
  • 本地图片未通过require()引入，直接给img的src赋值字符串路径
  • 动态路径拼接未提前静态导入：比如src={require(./icons/${iconName}.png)}，webpack无法静态解析这种动态路径，需提前导入所有可能用到的图片

React Native 项目常见原因 #

• 资源引用规则错误
  • 原生资源图片未放入对应平台目录：iOS需添加到Images.xcassets，Android需放入res/drawable（或对应分辨率目录）
  • 本地图片未使用require()包裹路径，React Native无法解析字符串形式的本地路径
  • 相对路径层级错误，嵌套组件中引用上级目录图片时层数计算失误
• 打包与缓存问题
  • 修改图片或路径后未重新打包项目，需执行react-native run-android/react-native run-ios重新构建
  • Metro服务缓存旧资源，需执行react-native start --reset-cache清除缓存后重启服务
• 文件命名与格式问题
  • 文件名包含空格、中文或特殊字符，React Native打包时无法识别
  • 图片格式不符合平台要求：比如Android对部分PNG压缩格式兼容差，iOS默认不支持WebP（需额外配置）
• 平台权限与配置问题
  • 远程HTTP图片在iOS端无法加载，未在Info.plist中配置NSAppTransportSecurity允许HTTP请求
  • Android端加载远程图片时，未在AndroidManifest.xml中添加INTERNET权限

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