React Native 0.68.2 iOS构建卡住、Xcode打开项目崩溃如何解决

故障表现 #

• 基于React Native 0.68.2 + Expo 45的iOS项目，经过数次代码修改、构建操作后，执行npm run ios会永久停在Planning Build阶段无进度
• 手动打开Xcode工作区文件时Xcode立刻进入无响应状态，常规清理缓存、重装Pods操作无效，仅能通过重新克隆Git仓库临时恢复
• 故障时终端构建输出固定如下：

(base) myMachine project-master % npm run ios                                            

> project@1.0.0 ios
> expo run:ios
✔ Installed pods and initialized Xcode workspace.
› Planning build (hangs here)

• 故障环境共性：macOS 12.x、Apple Silicon芯片、Xcode 13.x、未安装Watchman。

故障根因 #

三个问题叠加触发死锁：

• 缺失Watchman文件监听服务：没有Watchman时，Expo和Xcode的文件索引逻辑会递归遍历整个项目目录，包括node_modules和构建缓存目录，文件规模超过Xcode的单线程解析上限直接触发挂死
• Xcode DerivedData缓存损坏：多次增量构建后缓存内生成循环引用的索引条目，每次加载项目就会进入死循环
• Pods目录递归软链接bug：Expo 45适配React Native 0.68版本时，pod安装流程会在ios/Pods/Headers目录下生成指向自身的软链接，文件遍历到该路径时会无限递归。

永久修复步骤 #

按顺序执行，全程不需要重新克隆仓库：

1. 安装Watchman补全依赖，从根源解决异常文件遍历问题：

brew install watchman

安装完成后执行watchman --version确认输出正常版本号即可，M1芯片如果遇到权限报错，到系统设置「隐私与安全性-完全磁盘访问」中给当前使用的终端、Xcode开启权限。
2. 全量清理所有损坏的缓存文件，在项目根目录逐行执行以下命令：

# 清理JS依赖缓存
rm -rf node_modules
rm -rf package-lock.json yarn.lock
# 清理iOS构建、Pods相关缓存
rm -rf ios/Pods
rm -rf ios/build
rm -rf ~/Library/Developer/Xcode/DerivedData/*
# 清理Expo临时缓存
rm -rf .expo

3. 修复Pods递归软链接bug，打开项目下的ios/Podfile文件，在文件末尾添加如下post_install钩子：

post_install do |installer|
  # 移除Pods目录下的递归软链接，避免Xcode索引死循环
  Dir.glob(File.join(installer.sandbox.headers_root, '**', '*')).each do |path|
    next unless File.symlink?(path)
    link_target = File.readlink(path)
    File.delete(path) if link_target.include?(path)
  end
end

4. 重新安装依赖并触发构建：

# 重装JS依赖
npm install
# 重装iOS Pod依赖
cd ios && pod install && cd ..
# 启动构建
npm run ios

后续维护注意事项 #

• 不要卸载Watchman，这是React Native官方要求的必备依赖，缺失会导致各类文件监听、构建索引异常
• 后续如果再次出现构建卡顿，只需要执行步骤2的全量缓存清理命令即可恢复，不需要重新拉取仓库代码
• 不要在pod install执行完成前强行打开Xcode工作区，避免Xcode提前加载未生成完成的临时文件生成坏缓存。

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