IntelliJ IDEA 配置同步必须使用官方 Settings Sync 插件，通过 JetBrains Account 登录并手动勾选 Keymap、Plugins 等结构化设置；严禁用 macOS iCloud 云盘同步 .idea 目录或缓存文件，否则易引发冲突、启动失败或项目加载异常。
IntelliJ IDEA 配置同步该用 Settings Sync，别碰 iCloud 云盘
IDEA 的个性化设置（快捷键、插件、编辑器样式等）**不能也不该**通过 macOS 的 iCloud 云盘自动同步。iCloud 云盘会把 .idea 目录或 ~/Library/Caches/JetBrains/ 下的配置文件当作普通文件上传，但这些路径含符号链接、临时状态和平台相关缓存，直接同步极易导致冲突、启动失败或设置错乱。
JetBrains 官方唯一支持且稳定的跨设备配置同步机制是内置的 Settings Sync 插件，它只上传结构化配置元数据，不碰本地缓存或项目级 .idea 文件。
-
Settings Sync默认启用，无需额外安装；若不可见，请检查插件列表中Backup and Sync是否被禁用 - 必须使用
JetBrains Account登录（不是 Apple ID），登录方式包括：IDE 内Help > Register或通过JetBrains Toolbox统一登录 - 同步内容在
Settings > Backup and Sync中手动勾选，避免全选——比如Keymap和Plugins建议同步，但System Settings或Registry可能因 macOS 版本差异引发异常
iCloud 云盘同步 IDEA 项目文件时，必须避开 .idea 和 .iml
如果你确实要用 iCloud 云盘同步整个 IDEA 项目（例如共享给同事或备份源码），.idea 目录和 .iml 文件**必须排除在外**。它们记录的是本地 IDE 状态（如模块路径、编码格式、调试器断点），不同 Mac 上的路径、JDK 版本、插件版本稍有差异，就会让另一台机器打开项目时报 Cannot load module 或 Project SDK is not defined。
- 正确做法：只将项目根目录下的源码、资源、
pom.xml或build.gradle等构建文件拖入 iCloud 云盘；.idea和.iml加入.gitignore或手动删除后再上传 - 如果已误同步了
.idea，在另一台 Mac 上首次打开项目前，先删掉 iCloud 云盘里该项目下的.idea文件夹，再用 IDEA 重新“Open”项目，让它自动生成适配当前环境的配置 - iCloud 云盘对文件锁支持弱，多人同时编辑同一项目文件时可能产生冲突副本（如
MyClass.java (Conflicted Copy).java），建议仅用于单向备份或小团队轻量协作
桌面与文稿文件夹开启 iCloud 后，IDEA 项目路径要重定向
当你在系统设置中启用了 桌面与文稿文件夹 的 iCloud 同步，Mac 会把原 ~/Desktop 和 ~/Documents 软链接到 ~/Library/Mobile Documents/com~apple~CloudDocs/Desktop。这对 IDEA 来说不是问题，但有两个实际影响必须处理：
- IDEA 默认新建项目保存路径是
~/Documents，开启同步后，这个路径实际指向 iCloud 云盘子目录，上传大项目（如含node_modules或target）会显著拖慢 iCloud 后台队列，甚至触发“存储空间不足”警告 - 部分插件（如 Git 工具链）在读取
~下路径时可能因软链接层级变深而超时，表现为“Git root not found”或“Cannot detect VCS root” - 解决方案：在 IDEA 的
Settings > Appearance & Behavior > System Settings > Project Opening中，把默认项目位置改为非同步路径，例如/Users/yourname/Projects（需手动创建并确保不在 iCloud 云盘内）
同步中断时优先查 iCloud 状态栏图标，不是 IDEA 日志
当发现 IDEA 项目文件没出现在 iPhone 的“文件”App 或另一台 Mac 上，第一反应不该是翻 IDEA 的 idea.log，而应确认 iCloud 云盘本身是否处于健康同步状态。IDEA 不参与 iCloud 底层传输，它只是读写本地文件系统。
- 点击菜单栏右上角 iCloud 图标（云朵形状），查看是否显示“正在同步”或“所有文件均已上传”。若显示“暂停”或“错误”，说明问题出在系统层，与 IDEA 无关
- 打开访达，进入侧边栏
iCloud 云盘→桌面或对应文件夹，观察文件图标右下角是否有蓝色云朵标记；无标记表示未提交上传，可能是文件正在被 IDEA 进程占用（如编译中锁定out/） - 在
系统设置 > [你的姓名] > iCloud > 管理中检查剩余空间——iCloud 免费额度仅 5GB，一个未清理的target/目录就可能占满，导致新文件卡在“等待上传”状态
真正麻烦的不是操作步骤，而是混淆“谁管配置、谁管文件”——Settings Sync 管 IDEA 的“脑子”，iCloud 云盘只管“手脚能拿到的纸和笔”。一旦把脑图也塞进纸堆，两头都会出错。
