解决 Xcode 16 中 CocoaPods 的 "Unknown ISA PBXFileSystemSynchronizedRootGroup" 报错

问题描述

当在 Xcode 16 环境中运行 pod init 或 pod install 命令时，会出现以下关键错误：

RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup`

此错误通常发生在以下环境中：

• Xcode 16.0+
• CocoaPods 1.15.2
• macOS 15.0+
• 项目文件中出现新型的 PBXFileSystemSynchronizedRootGroup ISA 类型

错误原因

Xcode 16 引入了新的文件夹同步机制 PBXFileSystemSynchronizedRootGroup，而当前 CocoaPods 版本无法识别此类型。主要因项目文件中的新版格式（objectVersion = 77）和文件夹类型与 CocoaPods 的兼容性问题所致。

解决方案一：Xcode 内文件夹转换（推荐）

步骤操作

1. 在 Xcode 项目导航器中，右键点击蓝色的实体文件夹
2. 选择 "Convert to Group" 选项
3. 对项目中所有带蓝色图标的文件夹重复此操作

为何有效

此方法直接将 Xcode 16 新增的实体文件夹（PBXFileSystemSynchronizedRootGroup）转换为 CocoaPods 兼容的虚拟文件夹（PBXGroup），无需修改项目文件，是最安全的解决方案。

解决方案二：手动修改 project.pbxproj 文件

操作步骤

# 1. 关闭 Xcode 和所有相关进程
rm -rf Pods Podfile.lock

# 2. 打开项目文件
右键单击 YOUR_PROJECT.xcodeproj → "显示包内容" → 打开 project.pbxproj 文件

// 3. 查找并删除以下两行
- minimizedProjectReferenceProxies = 1;
- preferredProjectObjectVersion = 77;

// 4. 全局替换 ISA 类型
# 查找所有: PBXFileSystemSynchronizedRootGroup
# 替换为: PBXGroup

// 5. 修改项目版本号
objectVersion = 56; // 从 77 改为 56

// 6. 保存文件

执行命令

pod init  # 或 pod install

重新启动 Xcode 验证操作结果

注意

修改 project.pbxproj 存在风险，操作前务必：

1. 备份原始项目文件
2. 使用版本控制（如 Git）保存当前状态
3. 此操作可能会导致 Xcode 项目设置重置

解决方案三：清理 CocoaPods 缓存

当上述方法无效时，执行完整缓存清理：

pod deintegrate
pod cache clean --all
pod setup
pod install

技术原理分析

• PBXFileSystemSynchronizedRootGroup：Xcode 16 引入的新文件夹类型，用于实时同步文件系统
• objectVersion 77：Xcode 16 的项目格式版本，高于 CocoaPods 当前支持的版本（最高兼容 63）
• 转换操作实质：
  1. 将新型文件夹降级为传统 PBXGroup
  2. 项目格式版本从 77 降级到 56
  3. 移除不兼容的版本标记

最佳实践建议

1. 优先使用"文件夹转组"的图形化方案
2. 等待 CocoaPods 官方更新兼容 Xcode 16（追踪 GitHub Issue）
3. 当必须手动修改 pbxproj 时，使用专业文本编辑器进行操作

通过上述任一方法操作后，CocoaPods 可正常运行。大多数情况下，方案一即可解决问题且风险最小。若遇到文件访问异常（如类文件不可见），请转而采用方案二。