iCloud Drive同步失败可按五步解决：一、定位并删除带灰色感叹号的文件并清空废纸篓；二、用终端执行brctl reset --all重置同步状态；三、从iCloud网页下载文件后重建本地副本；四、用Cirrus工具扫描并重置阻塞文件；五、还原权限并清除扩展属性xattr。
如果您在Mac上发现iCloud Drive中存在同步失败的文件——例如文件图标显示为灰色感叹号、状态指示器长期停滞在“正在上传”或“等待上传”、右键菜单中“始终保留在本台Mac上”选项不可用，或文件在iCloud网页端可见但在本地访达中无法访问——则可能是由于该文件元数据损坏、权限异常、路径冲突或同步队列阻塞所致。以下是解决此问题的步骤：
一、定位并强制移除同步失败的文件
同步失败的文件常驻于本地但无法完成上传校验，其文件系统属性可能已“脏化”，继续保留将阻塞整个同步队列。直接删除可解除阻塞，且不会影响iCloud服务器端副本（前提是该文件已在云端成功存储）。
1、打开“访达”，在左侧边栏点击“iCloud云盘”。
2、浏览目录，寻找名称旁带灰色感叹号图标或无任何状态图标的文件或文件夹。
3、选中目标文件，按Command + Delete将其移至废纸篓。
4、立即清空废纸篓：右键点击废纸篓图标 → 选择“清空废纸篓”。
5、观察菜单栏iCloud图标是否由暂停状态转为活动状态；若仍停滞，继续执行后续步骤。
二、重置特定文件的同步状态（无需删除）
某些文件因扩展名非法、包含特殊字符、权限被锁定或已被其他进程占用，导致bird进程拒绝处理。此时可绕过图形界面，通过命令行重置其同步注册项，保留原始文件内容。
1、打开“终端”（应用程序 → 实用工具）。
2、输入以下命令并回车，以进入iCloud移动文档根目录：
cd ~/Library/Mobile\ Documents/
3、执行命令列出所有应用容器目录：
ls -1
4、识别疑似问题文件所在容器（如com~apple~CloudDocs对应通用iCloud Drive），进入该目录：
cd com~apple~CloudDocs
5、执行命令强制刷新该目录下所有项目的同步状态：
brctl reset --all
6、等待约15秒后，返回访达查看原文件状态指示器是否更新为实心云朵加向下箭头或无图标（已就绪）。
三、隔离并重建损坏文件的本地副本
当文件在iCloud网页端可见、但本地始终无法下载或显示为空白时，说明其本地缓存块已损坏，而服务器端副本完好。此时应放弃本地残留结构，重建干净副本。
1、在Safari中访问iCloud.com/iCloudDrive，使用同一Apple ID登录。
2、找到目标文件，点击右侧三个点图标 → 选择“下载”。
3、将下载的文件保存至桌面，确认其可正常打开。
4、在访达中，进入iCloud云盘对应路径，彻底删除原失败文件（含废纸篓清空）。
5、将桌面下载的新文件拖入iCloud云盘原位置，系统将发起全新上传流程。
四、使用Cirrus工具精准识别阻塞文件
Cirrus是一款专为macOS设计的iCloud诊断工具，可扫描bird进程内部同步队列，直接列出当前挂起、错误或超时的文件条目，避免盲目清理。
1、访问EclecticLight.co.uk官网，下载并安装最新版Cirrus for Mac（免费开源）。
2、启动Cirrus，点击“Scan”按钮开始分析本地同步状态。
3、在结果列表中筛选“Status”列为Error或Stalled的条目。
4、勾选对应文件行，点击右下角“Reset Sync State”按钮。
5、关闭Cirrus，观察访达中该文件状态图标是否在30秒内刷新；若未变化，手动右键选择“下载”。
五、重建文件关联与权限元数据
部分同步失败源于文件ACL（访问控制列表）或xattr（扩展属性）损坏，导致cloudd进程拒绝读取。需在不删除内容前提下重置底层元数据。
1、在访达中定位同步失败文件，右键 → “显示简介”。
2、滚动到底部，点击右下角锁形图标解锁，输入管理员密码。
3、在“共享与权限”区域，点击右下角齿轮图标 → 选择“还原所有权限”。
4、关闭“简介”窗口，打开“终端”。
5、输入以下命令（将“文件名”替换为实际名称，含空格需加引号）：
xattr -c "/Users/用户名/Library/Mobile Documents/com~apple~CloudDocs/文件名"
6、回车执行后，立即在访达中右键该文件 → 选择“始终保留在本台Mac上”。
