React Native CLI项目缺失fs/crypto等模块iOS运行报错解决方法

fs、crypto、util、events、querystring 都是Node.js运行时内置的核心模块，React Native运行在JavaScriptCore/Hermes引擎上，本身不包含Node.js核心库的实现。你之前参考的方案大多是针对Webpack打包的Web项目，直接照搬到Metro打包的RN项目里会出现兼容问题，手动安装的几个包本身也存在硬伤：

• 你安装的fs@0.0.1-security是npm官方占位包，本身没有任何可执行代码，仅用于占位防止恶意同名包投毒，完全不具备文件读写能力
• 你安装的crypto@1.0.1、原版util等包是为Node.js环境打包的，没有提供Metro可识别的模块入口配置，才会触发「无法解析模块配置中指定的main字段」的报错

第一步：卸载错误安装的不兼容包 #

在项目根目录执行对应包管理工具的卸载命令，把手动安装的Node核心模块同名包全部移除：

# npm用户执行
npm uninstall crypto fs util events querystring
# yarn用户执行
yarn remove crypto fs util events querystring

注意：不要在React Native项目里直接安装Node.js核心模块的同名npm包，这类包绝大多数是为Node/Web环境设计，不兼容RN运行环境。

第二步：按需替换为React Native兼容实现 #

根据你实际的功能需求，安装社区维护的RN专属兼容包，不要使用Node原生模块：

• 加密相关需求：将crypto替换为react-native-crypto，配套安装react-native-randombytes作为底层随机数依赖，安装完成后进入ios目录执行pod install完成原生依赖链接
• 基础工具函数需求：如果确实需要util、events相关能力，安装对应浏览器兼容版本后，必须在项目入口文件（默认是根目录的index.js）最顶部添加全局polyfill注入，代码要放在所有其他import语句之前：

import { LogBox } from 'react-native';
global.Buffer = global.Buffer || require('buffer').Buffer;
global.process = global.process || require('process/browser');
if (typeof BigInt === 'undefined') global.BigInt = require('big-integer')

• 文件读写需求：绝对不能使用Node的fs模块，React Native本身没有通用文件系统直接访问权限，要实现文件读写请安装react-native-fs，调用其提供的专属API即可
• URL参数处理需求：不要使用Node原生的querystring，替换为纯JS跨环境兼容的query-string包，不需要额外配置即可直接在RN环境运行

如果报错是第三方依赖间接引用Node模块导致的，优先把对应依赖升级到最新的React Native兼容版本，比盲目打polyfill稳定性更高。

第三步：全量清理缓存重新构建 #

依赖调整完成后必须清理所有层级的缓存，否则旧的模块解析缓存残留会导致报错持续出现：

# 清理watchman监听缓存
watchman watch-del-all
# 移除旧依赖和锁文件
rm -rf node_modules && rm -rf yarn.lock package-lock.json
# 重新安装JS依赖
npm install # yarn用户替换为yarn install
# 清理iOS构建缓存并重新安装Pods
cd ios && rm -rf Pods && rm -rf Podfile.lock && pod install && cd ..
# 带重置缓存参数启动Metro服务
npx react-native start --reset-cache
# 新开终端窗口，重新运行iOS应用
npx react-native run-ios

后续如果再遇到Node核心模块缺失报错，优先找React Native专属的兼容实现，不要直接安装Node同名包：

• 流处理需求不要直接装stream，用readable-stream替代
• 路径处理需求不要直接装path，用path-browserify替代
• 所有polyfill注入代码必须放在入口文件最顶部，否则会出现注入不生效的问题

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