React Native执行pod install后iOS编译失败问题排查

问题拆解与对应解决方案 #

1. punycode模块弃用警告 #

• 原因：punycode是Node.js内置模块，高版本Node已标记弃用，但部分依赖库仍在调用该模块
• 解决：
  • 排查项目依赖树，找到调用punycode的第三方包，优先升级到适配高版本Node的最新版本
  • 若无法升级目标包，可手动安装punycode包（npm install punycode），同时在项目根目录创建.npmrc文件并添加legacy-peer-deps=true，规避版本冲突问题

2. VisionCamera缺失react-native-worklets-core提示 #

• 原因：VisionCamera v3及以上版本强制依赖react-native-worklets-core作为核心运行依赖，未安装或配置不完整
• 解决：
  • 安装依赖：npm install react-native-worklets-core
  • 进入iOS目录，检查Podfile是否自动引入该依赖，若未自动添加，手动插入代码：pod 'react-native-worklets-core', :path => '../node_modules/react-native-worklets-core'
  • 执行pod install后，重启Metro服务并清理缓存：npx react-native start --reset-cache

3. 自动分配iOS版本提示 #

• 原因：项目未指定明确的iOS部署目标版本，CocoaPods自动分配默认版本，与部分依赖的最低版本要求不匹配
• 解决：
  • 打开iOS目录的Podfile，修改platform :ios, 'XX.XX'为符合依赖要求的版本（例如VisionCamera要求iOS 13.0+，则设置为platform :ios, '13.0'）
  • 打开Xcode，在项目目标的Build Settings中确认iOS Deployment Target与Podfile中版本保持一致

4. Pods项目生成重复UUID #

• 原因：CocoaPods缓存残留或项目配置冲突，导致生成的Pods项目中出现重复的UUID标识
• 解决：
  • 彻底清理缓存与旧Pods文件：

    cd ios
    pod deintegrate
    pod clean
    rm -rf Pods
    rm Podfile.lock
    rm -rf ~/Library/Caches/CocoaPods
    rm -rf ~/Library/Developer/Xcode/DerivedData
    

  • 重新执行pod install
  • 若问题仍存在，检查项目中是否有自定义Pod配置或本地依赖，避免重复引入同一库

编译失败最终排查方向 #

若上述警告未解决，编译失败通常是多问题叠加导致：

• 优先解决react-native-worklets-core缺失问题，这是VisionCamera运行的核心前提，缺失会直接触发编译报错
• 确保iOS部署版本统一，避免依赖版本不兼容
• 清理缓存后重新构建，排除缓存冲突引发的隐性错误

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