icloud文件夹同步死锁常由权限递归错误引发，表现为无法写入元数据、生成.icloud占位符或提交变更，卡在“等待上传”状态；需通过ls -le检查权限、brctl日志定位问题，再用chown、chmod和xattr精准修复，避免chmod -r 777。
icloud 文件夹同步死锁，如果根源是权限递归错误（比如子目录或文件被设为只读、所有权异常、acl 冲突），系统就无法写入元数据、生成 .icloud 占位符或提交变更，导致整个路径卡在“等待上传”状态。这类问题常出现在手动修改过文件权限、用 root 操作过 icloud 目录、或从外部磁盘迁移过 desktop/documents 文件夹后。
确认是否为权限类死锁
打开终端，运行以下命令快速筛查：
- 检查 iCloud 同步根路径权限： ls -le ~/Library/Mobile\ Documents/ 确认该目录所有者是你当前用户，且至少有 drwxr-xr-x 权限（即用户可读写执行）。
- 抽查卡住的文件夹： ls -le ~/Desktop/卡住的文件夹 若出现 restricted、no access 或权限字段含 000，基本可判定为权限阻塞。
- 查看同步日志线索： brctl log -w | grep -i "permission\|denied\|access" 若持续滚动类似 "Operation not permitted" 或 "Failed to set xattr"，就是权限问题的典型日志特征。
修复递归权限与所有权
不要直接 chmod -R 777，这会破坏 macOS 的安全机制。应精准重置：
- 把整个 iCloud 同步范围的所有权归还给你自己： sudo chown -R $(whoami):staff ~/Library/Mobile\ Documents/ ~/Desktop/ ~/Documents/
- 恢复标准 Unix 权限（用户可读写，组和其他仅可读）： find ~/Library/Mobile\ Documents/ -type d -exec chmod 755 {} \; find ~/Library/Mobile\ Documents/ -type f -exec chmod 644 {} \;
- 清除可能干扰的扩展属性（如 com.apple.FinderInfo、com.apple.quarantine）： xattr -rc ~/Library/Mobile\ Documents/ 此操作安全，不影响文件内容，但能解除因 quarantine 或 Finder 锁定导致的同步阻塞。
绕过权限冲突的临时同步策略
若修复后仍卡在特定子文件夹（例如含 Git 仓库、.vscode、node_modules），说明其内部结构触发了 iCloud 的保护逻辑：
-
将敏感子目录移出 iCloud 路径：
把 ~/Desktop/project/.git 整个剪切到 ~/LocalDev/project/.git（非 iCloud 路径），再在原位置建符号链接：
ln -s ~/LocalDev/project/.git ~/Desktop/project/.git - 对整层目录禁用 iCloud 同步（不删除文件）： 在访达中右键点击该文件夹 → “还原下载”，等图标变成云朵状后，再右键 → “从iCloud云盘移除”，文件保留在本地，不再参与同步队列。
- 用 Cirrus 工具单独重置卡住项： 下载 Cirrus（EclecticLight.co），启动后进入 Sync Status 面板，找到标红的 stuck item，选中 → “Reset Item”。它会跳过系统级权限检查，强制刷新该条目的同步状态。
预防后续递归权限错乱
iCloud 不支持对同步目录做深度权限定制。日常使用中需规避以下行为：
- 避免用 sudo cp、sudo rsync 向 Desktop/Documents 写入内容；
- Git 仓库尽量放在非 iCloud 路径（如 ~/Projects），或在 repo 根目录添加 .nosync 文件（部分工具识别）；
- 启用“优化 Mac 存储”时，确保关键文件已设为“始终保留在本台 Mac 上”，防止系统自动剥离权限元数据。
