VSCode Settings Sync 必须手动开启并验证：执行 Preferences: Turn on Settings Sync，仅支持 GitHub 账户（非 Microsoft）并授权 gist、user:email、read:user 权限；成功后状态栏显示蓝色云图标且悬停为 “Sync: On”；terminal.integrated.profiles.*、python.defaultInterpreterPath 等平台路径字段被静默过滤，需用 settingsSync.ignoredSettings 主动排除；插件同步仅传 ID 列表，不自动安装，跨平台需本地适配或手动重装；真实错误需查开发者工具 Console 中 sync/gist/401/403 日志。
VSCode 跨平台同步不是“开个开关就完事”，它默认不启用，且不同系统间存在路径、插件兼容、权限等隐性冲突。必须手动开启并验证关键项，否则同步后很可能出现插件失效、快捷键错乱或设置丢失。
如何确认 Settings Sync 已真正启用
很多人以为登录了 Microsoft 账号就自动同步了，其实不是。VSCode 的账号登录和 Settings Sync 是两套独立机制。
- 按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Turn on Settings Sync...并执行 - 必须选择 GitHub 作为身份提供方（Microsoft 账号目前不支持 Settings Sync 后端）
- 授权时要允许访问
gist权限，否则会卡在“Waiting for GitHub…” - 同步成功后，左下角状态栏会出现一个云朵图标
☁️，鼠标悬停能显示上次同步时间
哪些配置会跨平台失效，必须手动排除
VSCode 会自动跳过 machine 作用域的设置，但很多用户自定义项仍含平台敏感路径或行为，同步后直接报错或静默失效。
-
terminal.integrated.profiles.linux/.windows/.osx这类平台专属终端配置，同步到其他系统会丢弃或引发启动失败 - 插件如
ms-vscode.cpptools或ms-python.python，其python.defaultInterpreter或cmake.cmakePath若填了绝对路径（如C:\Python39\python.exe），在 macOS 上必然失效 - 使用
settingsSync.ignoredSettings主动忽略高风险项，例如："python.defaultInterpreter"、"terminal.integrated.shell.*"、"editor.fontFamily"（字体名在不同系统可能不存在）
插件同步后不生效？先查这三件事
同步扩展列表 ≠ 自动安装 + 启用。尤其跨平台时，部分插件需本地适配或手动触发安装。
- 检查插件页右上角是否显示
Sync: Enabled，若为灰色说明未参与同步 - 打开命令面板，运行
Extensions: Show Enabled Extensions，确认关键插件确实在“已启用”列表里 - 某些插件（如
rust-analyzer）在不同平台需下载对应平台的二进制，首次启动时可能卡住——关掉 VSCode，手动运行code --install-extension rust-lang.rust-analyzer再重试
同步失败时最该看的日志位置
别只盯着弹窗提示，VSCode 把真实错误藏在开发者工具里。
- 按
Ctrl+Shift+I（或Cmd+Option+I）打开开发者工具 - 切换到
Console标签页，筛选关键词：sync、gist、401（认证失败）、403（权限不足） - 常见错误：
Failed to fetch gist多因企业防火墙拦截gist.github.com；Invalid Gist ID说明本地配置里的sync.gist值已失效，需重置同步
跨平台同步真正的难点不在“怎么开”，而在识别哪些东西不该同步、哪些插件需要二次初始化、以及出问题时去哪里找真实日志——这些细节不处理，同步反而会放大环境差异。
