iCloud同步出错后需三步修复：先删除带灰色感叹号的残留文件并清空废纸篓；再重置CloudDocs缓存或执行brctl reset --all；最后清理~/Library/Caches/CloudKit和~/Library/Application Support/Apple/CloudDocs/session中的临时数据块。
Mac本地iCloud同步出错后，常在后台残留损坏的缓存副本——这些文件既无法正常上传，又阻塞后续同步队列，图标显示灰色感叹号，右键菜单缺失“始终保留在本台Mac上”选项，甚至导致整个iCloud云盘卡在“正在上传x个项目”状态。
定位并强制删除同步失败的残留文件
同步失败的文件往往已脱离正常同步流程，但其元数据仍被bird进程锁定，继续驻留将拖慢全盘同步速度。必须从访达中直接清除，且需清空废纸篓才算真正释放。
1、打开“访达”，左侧边栏点击“iCloud云盘”。
2、逐级浏览目录，重点查找名称旁带灰色感叹号图标或完全无状态图标的文件与文件夹——这类文件大概率已同步中断超48小时。
3、选中目标项，按Command + Delete移入废纸篓；若提示“文件正被使用”，请先执行下一部分的进程重启步骤再重试。
4、右键点击桌面废纸篓图标 → 选择“清空废纸篓”；这一步不可跳过，否则空间不会释放。
重置CloudDocs缓存目录重建同步上下文
当多个文件同时卡住、或删除后仍反复出现新灰色图标，说明~/Library/Application Support/CloudDocs目录本身已损坏。此时不能只删文件，而要重置整个同步缓存结构。
方法一：终端命令重命名缓存（推荐）
1、关闭所有文档类应用，特别是Pages、Numbers、Keynote、Bear和Notability。
2、打开“终端”（应用程序 → 实用工具），依次执行：
cd ~/Library/Application\ Support
mv CloudDocs CloudDocs.bak
3、进入“系统设置”→“Apple ID”→ 点击右上角“退出登录”，确认退出后重新输入Apple ID密码登录。
4、等待2～3分钟，系统自动生成全新CloudDocs文件夹，并开始从云端拉取最新状态映射表。
方法二：不退出账户的轻量替代（仅限小范围卡顿）
在终端中执行：
brctl reset --all
该命令不删除本地文件，仅刷新bird进程对当前目录的注册状态，适用于单个子文件夹同步异常的场景。
清理深层隐藏的同步临时块
iCloud Drive在上传中断、网络抖动或App崩溃时，会把未完成的数据块写入系统级缓存路径，这些文件默认不可见，Finder也搜不到，但实际占用空间可达数GB。
第一步：清空CloudKit staging区
1、访达中按Command + Shift + G，输入：
~/Library/Caches/CloudKit/
2、回车后，按“修改日期”排序，重点关注含“upload”“staging”“pending”字样的文件夹，以及创建时间早于7天的任意子目录。
3、选中后按Command + Delete移入废纸篓。
第二步：扫荡CloudDocs session残留
1、再次按Command + Shift + G，输入：
~/Library/Application Support/Apple/CloudDocs/session
2、清空该文件夹内全部内容——这里存放的是上传会话快照，长期不清理会导致bird反复尝试重传已失败的块。
注意：执行前务必确认没有正在协作编辑的Pages或Keynote文档，否则可能中断他人实时编辑。
