React Native项目Android模拟器运行报EISDIR目录读取非法操作错误

错误触发场景 #

项目长期基于iOS Xcode模拟器调试运行，全流程功能无异常；切换到Android模拟器启动同一项目时，控制台抛出EISDIR: illegal operation on a directory, read的目录读取类异常。

根本产生原因 #

该错误本质是Metro打包服务（基于Node.js运行时）执行文件读取操作时，传入的路径指向了一个文件夹而非普通文件，触发了Node.js fs模块的非法操作校验，核心是跨端路径解析逻辑不兼容：

• iOS端的资源打包、路径解析逻辑相对宽松，遇到指向目录的无效路径时会自动跳过，不会触发硬校验，因此长期在iOS模拟器运行时不会暴露问题
• Android端的文件系统访问、Metro资源扫描规则更严格，遇到把目录当文件读取的操作时，会直接抛出EISDIR异常
  常见的具体触发点包括：
• 资源导入时路径误写，把文件所在的文件夹路径当成了具体文件路径引入
• Metro打包配置中存在指向目录的无效静态资源路径
• 双端路径映射未做兼容，硬编码了iOS专属的文件路径规则
• 第三方原生模块的初始化参数传入了目录路径，未做安卓端的合法性兜底

可落地解决方案 #

• 优先清理全链路缓存后重新启动打包服务：依次执行watchman watch-del-all、删除node_modules目录后重新安装依赖，再清理本地Metro临时缓存文件，通过npx react-native start --reset-cache参数启动打包服务，排除缓存导致的路径解析错误
• 逐一排查本地资源导入逻辑：检查所有require()、import引用本地图片、字体、配置文件的代码，确认导入路径是具体的文件路径，而非文件所属的文件夹路径，这类误写在iOS端通常不会触发报错，是安卓端出现该类问题的最高发原因
• 检查安卓原生层的路径配置：核对android/app目录下的构建脚本、清单文件中涉及的本地资源引用，确认自定义字体、本地配置文件的引用指向具体文件，而非文件所在的目录
• 排查第三方依赖的双端兼容性：如果近期新增了资源类、文件读取类的第三方依赖，检查依赖初始化时传入的路径参数，确认没有传入仅在iOS端有效的路径值

排查时可通过npx react-native start --verbose开启全量日志，直接定位到Metro尝试读取目录的具体代码行，可大幅缩短定位时长

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