Sync Settings 在 Sublime Text 4 上可用，但需插件≥v3.0且ST4内核较新；必须先确保Package Control正常，再安装插件；Setup需手动触发并仅授权gist权限；上传成功不等于同步成功，须确认gist_id写入配置；离线可用sync_local模式。
Sync Settings 在 Sublime Text 4 上能用，但必须满足两个硬性前提：插件版本 ≥ v3.0，且 ST4 已升级到较新内核（2026 年主流发行版基本达标）。装不上、没菜单、点不动，90% 是卡在这两步之前。
Package Control 没跑通，Sync Settings 根本不会加载
插件依赖 Package Control 启动，不是“装完就出现”。先验证它是否真在工作：
- 按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Package Control: Install Package—— 能执行并弹出搜索框才算 OK - 如果报错或无响应，说明 Package Control 损坏或未安装。此时别急着搜
Sync Settings，先重装 Package Control（官网最新命令已适配 ST4，勿用旧版哈希校验失败的脚本） - 确认成功后，再执行
Package Control: Install Package→ 输入Sync Settings→ 回车（注意别选Sync Settings (Deprecated)）
Sync Settings: Setup 必须手动触发，且 token 必须带 gist 权限
安装完不会自动弹窗、不会后台同步、也不会监听文件变化。一切从 Sync Settings: Setup 命令开始：
- 调出命令面板，输入并运行
Sync Settings: Setup - 跳转到 GitHub OAuth 页面后，**只勾选
gist** —— 其他权限（如repo）不仅多余，还可能因组织策略被拒绝，导致 token 创建失败 - token 只显示一次，复制后立刻粘贴进 Sublime 的输入框；若误粘到浏览器地址栏或文本编辑器里，
Packages/User/Sync Settings.sublime-settings中的github_token字段就是空的，后续所有上传都静默失败 - 检查该配置文件，确认
gist_id和github_token都是非空字符串，才算真正落地
上传成功 ≠ 同步成功，gist_id 不写入等于白传
控制台显示 Upload completed 很有迷惑性——它只表示 HTTP 请求发出去了，不代表 Gist 创建成功、内容写入成功：
- 常见失败原因：token 过期/错误、网络中断、GitHub gist 服务临时不可用
- 上传后立刻打开
Packages/User/Sync Settings.sublime-settings，看gist_id是否已写入；为空？说明这次上传没真正落库，下次Upload会新建一个 Gist，旧的再也找不回来 - 若控制台报
401 Unauthorized，基本锁定为 token 问题，需重新Setup - 插件只同步
Packages/User/下的文件，.sublime-snippet在Packages/Emmet/？不会打包；Preferences.sublime-settings在Packages/Default/？也不会上传
公司网络/离线环境直接用 sync_local 模式
如果机器无法访问 GitHub（比如企业内网、机场 Wi-Fi 限制、或你单纯不想把配置上传云端），Sync Settings 内置了纯本地模式，零网络依赖：
- 打开
Preferences → Package Settings → Sync Settings → Settings - 填入：
{ "sync_local": true, "local_path": "/path/to/shared/folder/sublime-sync" } -
local_path必须是所有设备都能访问的路径：可以是 NAS 挂载点、OneDrive 同步目录、甚至 USB 设备挂载路径（但需确保每次插入后路径一致） - 首次仍需手动运行
Sync Settings: Upload把当前配置写入本地目录；之后Download即可拉取，全程不走网络
真正容易被忽略的是：同步不是单向“上传一次就完事”，而是“上传→他人下载→他人改→再上传→你再下载”的闭环。只要任意一端漏掉 Download 或误删了 gist_id，配置就会脱节。建议把 gist_id 手动备份在密码管理器里，比靠记忆靠谱。
