报错“Unable to read syncLocalSettings.json. Make sure its Valid JSON”本质是本地元数据文件损坏，需删除该文件后重启VSCode并重新同步；该文件由插件自动生成，不可手动修复，删后重建最安全。
Settings Sync 报错 “Unable to read syncLocalSettings.json. Make sure its Valid JSON”
这是 VSCode 同步插件（尤其是旧版 code-settings-sync 扩展）在更新后最常触发的崩溃点，本质是本地元数据文件损坏，不是网络或账号问题。常见于 Windows 首次安装、升级后自动重建配置失败，或手动编辑过 syncLocalSettings.json 导致语法错误。
解决方法极简但必须精准：
- 关闭 VSCode
- 定位并删除该文件：
C:\Users\<yourname>\AppData\Roaming\Code\User\syncLocalSettings.json（Windows）；~/Library/Application Support/Code/User/syncLocalSettings.json（macOS）；~/.config/Code/User/syncLocalSettings.json（Linux） - 重新打开 VSCode，再执行一次同步登录流程（如
Syncing: Upload Settings），文件会干净重建
注意：别试图“修复”这个 JSON——它由扩展自动生成，手动改极易出错；删了比修更安全。
更新后同步命令消失或 Syncing: Upload Settings 不响应
VSCode 1.84+ 已默认禁用原生 Settings Sync，而第三方扩展如 shanalikhan.code-settings-sync 在 2026 年已归档停更。如果你刚更新 VSCode，发现命令面板里搜不到 Syncing: Upload Settings，大概率是扩展已被自动禁用或与新版不兼容。
验证和应对步骤：
- 打开扩展视图，搜索
code-settings-sync，确认状态是否为 “Disabled” 或版本号低于 v3.4.3（当前兼容上限） - 若已禁用，点击启用；若版本过旧，先卸载，再从 VSCode Marketplace 手动安装最新可用版本（截至 2026 年 8 月，v3.4.3 是最后一个支持 VSCode 1.84+ 的稳定版）
- 仍无命令？重启 VSCode 后，在命令面板中**手动输入全名**：
Syncing: Upload Settings—— 不要依赖模糊匹配，部分版本不注册快捷别名 - 如仍失败，说明该扩展已彻底失效，需切换至 GitHub Gist + 脚本方案（见下一条）
GitHub Token 失效导致同步卡在 “Invalid / Expired GitHub Token”
插件更新后常重置或忽略旧 Token，尤其当你之前用的是 GitHub Classic Token（2023 年后 GitHub 已弃用），或企业网络策略刷新了 OAuth 会话。报错信息通常出现在开发者控制台（Ctrl+Shift+U），但 UI 层只显示灰色云图标或无反应。
必须重生成并注入新 Token：
- 访问
https://github.com/settings/tokens，点击 “Generate new token” → “Generate new token (classic)” - 勾选
gist（必选）、user:email、read:user（授权必需） - 复制生成的 token
- 在 VSCode 命令面板运行
Sync: Advanced Options→Edit Extension Local Settings，粘贴到token字段 - 或者直接编辑
syncLocalSettings.json文件，替换"token": "xxx"的值（确保 JSON 格式正确，加英文双引号）
Token 生效前，VSCode 不会尝试连接 gist，所以这一步跳过就永远同步不了。
同步成功但插件没装上，或装了一半卡在 Installing…
Settings Sync 只同步 extensions.json 列表，不执行安装动作。插件更新后，旧版同步逻辑可能把新版本插件识别为“冲突”，导致静默跳过或卡住。
关键操作不是重试同步，而是干预安装流程：
- 打开扩展视图（
Ctrl+Shift+X），看右上角是否有 “Extensions to install” 横幅 —— 有就点它 - 若无横幅，但在列表顶部看到 “Recommended extensions”，点右侧 “Install All”
- 仍有插件显示 “Installing…” 卡死？右键该插件 → “Install Another Version”，选一个稳定版（比如避开 alpha/beta 版本）
- 对反复失败的插件（如
ms-python.python），可在设置中添加忽略："settingsSync.ignoredExtensions": ["ms-python.python"]
跨平台时尤其要注意：Windows 上的 ms-vscode.powershell 在 macOS 同步后会被跳过，且不提示——这不是 bug，是设计行为，容易被当成失败。
真正麻烦的不是报错本身，而是同步机制对“更新”的语义模糊：插件更新 ≠ 同步更新，Token 更新 ≠ 配置更新，VSCode 更新 ≠ 扩展兼容。每次大版本升级后，都要单独验证 Token、命令注册、安装触发这三环，缺一不可。
