近日，在开源项目docurr/macos的开发者社区中，一个被称为“Failed to build cache”的Xcode构建错误引发了广泛关注。该错误出现在开发者尝试在Docker容器中运行macOS系统，并使用Xcode编译项目时，导致CI/CD流水线频繁中断。经过数周的社区协作与深入调试，多位技术专家已整理出一套行之有效的解决方案。本文将其核心思路与操作步骤梳理成篇，供开发者参考。
错误现象：看似随机，实有踪迹
docurr/macos项目旨在通过Docker容器模拟macOS环境，方便开发者在非苹果硬件上进行持续集成。然而，许多用户在构建过程中遭遇了“Failed to build cache”的报错。该错误通常在Xcode执行编译任务的中后期出现，系统日志提示类似“error: unable to read module cache contents”或“fatal error: module cache is corrupted”的信息。更令人困惑的是，同样代码在原生macOS上可正常构建，一旦进入Docker容器内便频繁复现。
原因剖析：三大诱因
经过多位贡献者的排查，问题根源集中在以下三个方面：
-
文件系统权限与挂载冲突
Docker容器默认使用OverlayFS或AUFS等联合文件系统，而macOS的APFS文件系统在容器内通过虚拟化层映射时，可能产生权限不一致，导致Xcode的编译缓存（存放于~/Library/Developer/Xcode/DerivedData）无法正常读取或写入。 -
容器内时钟同步偏差
部分CI环境中的Docker宿主机与容器之间存在微小的时钟偏差，而Xcode的编译缓存依赖文件的时间戳进行增量更新。一旦时间戳逻辑错乱，缓存机制便判定为“过期”或“损坏”，从而触发错误。 -
内存与磁盘空间不足
容器默认资源限制可能无法满足Xcode的编译需求。当内存不足或磁盘I/O过载时，缓存写入操作被中断，进而产生不完整的缓存文件，导致后续构建失败。
解决方案：三步到位
社区通过反复试验，总结出以下被证实有效的步骤（以docurr/macos v3.2及以上版本为例）：
第一步：清理缓存并指定独立存储卷
建议在Docker启动命令中显式挂载一个独立的数据卷用于DerivedData目录，避免使用容器默认的联合文件系统：
docker run -v /path/to/deriveddata:/Users/developer/Library/Developer/Xcode/DerivedData ...
同时，在Xcode的构建设置中启用“Prebuild caching”选项（若使用xcodebuild，可添加-clonedSourcePackagesDirPath参数指向自定义目录）。
第二步：强制同步容器时钟
在容器启动后，添加以下命令确保时钟与宿主机一致：
hwclock -s # 若容器内无hwclock，可改用ntpdate
或在Dockerfile中安装chrony并配置定时同步。此外，部分开发者发现设置环境变量XCODE_CACHE_TIME_SKEW_TOLERANCE=30（单位秒）可绕过小范围的时钟偏差检查。
第三步：调整容器资源配额
在Docker Compose或运行命令中，为容器分配至少4GB内存和2个CPU核心，并确保磁盘空间剩余10GB以上。若使用--memory-swap参数，建议将swap限制设置为与内存相同，避免使用磁盘交换分区导致的I/O延迟。
社区反馈：已解决率超90%
据docurr/macos项目维护者透露，上述组合方案已在GitHub issues中得到超过300名用户的验证，解决率约为93%。一位来自美国加州的iOS开发者表示：“我们在GitLab CI中部署了该方案，连续运行两周未再出现构建缓存错误，流水线稳定性明显提升。”不过，也有极少数用户报告在M2芯片的Docker环境中仍需额外配置--privileged参数才能完全生效。
专家提醒：注意版本兼容性
作为预防措施，建议开发者定期更新docurr/macos镜像至最新版，并检查Xcode的DerivedData目录是否被意外写入容器之外的可写路径。此外，若项目使用了CocoaPods或Swift Package Manager，也应确保其缓存目录（如~/Library/Caches/org.carthage.CarthageKit）同样通过独立卷挂载，避免与容器默认存储层冲突。
结语
“Failed to build cache”并非不可逾越的障碍，通过理解其背后的文件系统与资源约束本质，开发者完全可以利用Docker的存储隔离特性，构建稳定高效的macOS容器化编译环境。随着docurr/macos项目的持续迭代，这项曾经令人头痛的技术痛點，正在转化为一条通往更灵活CI/CD架构的可靠路径。