如何让xcodebuild archive复用DerivedData缓存完成iOS应用归档

xcodebuild 无法复用DerivedData缓存从来不是"强制开启"就能解决的问题，CI环境下90%的缓存失效都是配置冲突或缓存内容不完整导致的，按以下步骤排查配置即可实现稳定增量编译：

1. 修正Fastlane build_app 配置，关闭触发全量编译的默认参数 #

build_app 多个默认参数会主动打断增量编译逻辑，必须显式覆盖：

• 将clean参数设为false：绝大多数CI配置习惯默认开启构建前清理，该参数会直接删除DerivedData下的对应构建产物，必然触发全量编译
• 显式指定固定的DerivedData路径：不要使用xcodebuild默认生成的随机临时路径，通过derived_data_path参数固定到项目内的相对路径，保证和Github Actions缓存路径完全一致
• 将force_build_artifacts参数设为false：该参数开启时会忽略所有已存在的编译产物，强制重新生成所有模块
• 显式传入增量编译参数：通过xcargs传入编译标识，关闭Xcode新版本默认开启的沙箱限制（该限制会导致脚本产物每次被判定为变更）

可直接参考的lane配置：

lane :release_build do
  build_app(
    workspace: "你的项目名.xcworkspace",
    scheme: "你的构建Scheme",
    configuration: "Release",
    clean: false,
    derived_data_path: "./DerivedData",
    force_build_artifacts: false,
    export_method: "app-store", # 按你的实际导出类型修改
    xcargs: "-incremental ENABLE_USER_SCRIPT_SANDBOXING=NO COMPILER_INDEX_STORE_ENABLE=NO",
    # 其余IPA导出配置按你的需求保留
  )
end

2. 修正Github Actions缓存配置，保证缓存元数据完整 #

很多场景下缓存失效不是xcodebuild的问题，是缓存时漏存了增量校验必需的元文件：

• 缓存路径必须覆盖你指定的整个DerivedData目录，不要只缓存DerivedData/Build子文件夹，xcodebuild做增量校验需要读取目录下的编译状态、文件哈希等元数据，缺了就会直接判定缓存无效
• 缓存key必须绑定影响编译结果的核心维度，避免无效缓存复用或缓存频繁失效，参考key规则：ios-archive-${{ runner.os }}-xcode${{ matrix.xcode_version }}-${{ hashFiles('Podfile.lock', '项目名.xcodeproj/project.pbxproj', 'Package.resolved') }}
• 缓存恢复后补一步权限修正：Github Actions恢复缓存时可能修改文件权限，xcodebuild遇到权限异常的缓存文件会直接忽略重编，加一行命令修正权限即可：chmod -R 755 ./DerivedData

3. 调整项目编译配置，消除隐式全量编译触发点 #

• 检查Scheme的Archive配置：如果开启了Find Implicit Dependencies，缓存恢复时文件修改时间的微小变动就会触发所有依赖模块重编，依赖版本固定的话可以关闭该选项，手动配置target依赖关系
• 避免编译前修改会触发全量重编的文件：比如不要在编译步骤前修改project.pbxproj、Build Settings配置、所有target的前缀头文件，版本号、build号这类修改尽量放到编译完成、导出IPA之前执行
• 不要随意加全量编译相关的编译标识：比如不要在Release配置里加WHOLE_MODULE_OPTIMIZATION以外的全模块编译参数，避免覆盖xcode默认的增量判断逻辑

4. 进阶优化方案 #

如果以上配置调整后缓存命中率仍达不到预期，可以直接使用基于模块哈希的第三方xcode构建缓存工具，这类工具会跳过xcode自带的文件修改时间校验逻辑，直接按源码内容哈希判断是否需要重编，CI环境下的缓存命中率远高于原生DerivedData缓存。

注意：不要使用网络存储或机械盘作为CI runner的工作磁盘，这类磁盘的文件时间戳读取异常会导致xcodebuild的增量校验逻辑完全失效，必须使用本地SSD存储运行构建任务。

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