切换Git分支时出现SPM unknown error reference not found报错解决方案

这个报错本质是Swift Package Manager（SPM）的本地依赖缓存状态和项目分支记录的依赖信息不同步导致的，常见触发场景有三个：

• 切换分支后，新分支的Package.resolved记录的私有依赖版本、提交哈希，和本地SPM缓存里对应依赖仓库存储的远端跟踪引用不匹配。如果私有仓库的main分支有过强推、提交重置、历史改写操作，本地缓存里的refs/remotes/origin/main引用没有同步更新，SPM做增量包校验的时候不会主动拉取最新远端引用，直接读取本地缓存就会报找不到对应ref的错误。
• 切换分支时Xcode触发的是轻量增量包校验，不会自动刷新所有依赖的远端元数据，当新分支调整了私有依赖的版本指向，本地缓存里没有对应分支/提交的引用记录时就会直接抛错，不会自动触发fetch修复。
• 少数情况是之前拉取私有依赖的时候网络中断、权限校验临时失败，导致本地缓存的依赖git仓库元数据损坏，丢失了远端分支的引用记录。

• 单包更新修复（10秒内完成，优先试）
  打开Xcode选中项目，切到Package Dependencies面板，在依赖列表里找到报错的私有仓库，右键选择Update Package，Xcode只会单独拉取这个依赖的最新远端引用和提交记录，不会改动其他已缓存的依赖，完成后会自动重新触发项目编译。
• 手动刷新单包缓存引用（如果Xcode内更新失败）
  打开终端进入SPM的本地仓库缓存目录，找到对应私有仓库的裸仓库目录，手动执行fetch同步远端引用：

  cd ~/Library/Caches/org.swift.swiftpm/repositories/
  # 进入对应私有仓库的目录，目录名一般会包含你的私有仓库域名和仓库名
  git fetch origin
  

  执行完成后回到Xcode重新触发包解析即可，不需要删除任何已有缓存。
• 单包缓存清理（上面两种方法都无效时使用）
  执行终端命令只删除出问题的私有依赖缓存，不需要清理全量SPM缓存：

  # 替换<你的私有仓库名>为实际的仓库名称关键词
  rm -rf ~/Library/Caches/org.swift.swiftpm/repositories/*<你的私有仓库名>*
  rm -rf ~/Library/Developer/Xcode/DerivedData/$(ls -t ~/Library/Developer/Xcode/DerivedData | head -1)/SourcePackages/checkouts/*<你的私有仓库名>*
  

  执行完回到Xcode，SPM只会重新拉取这一个私有依赖，不需要重新下载所有第三方包，耗时远低于全量重置缓存。

全量重置SPM缓存相当于删除所有依赖的本地缓存重新拉取，是最后兜底的方案，绝大多数场景下用上面三种方法都能快速修复。

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