Files

T

purp1e 4263d6a25d Redesign Zed Gist sync workflow

2026-07-30 12:53:31 +08:00

7.8 KiB

Raw Permalink Blame History

Zed 设置同步手册

本方案把 Zed 的设置、键位、Tasks、文件排除规则、代码片段和主题整理为一个扁平的 zed-settings-sync.json，通过 GitHub Gist 在机器间同步。同步文件内部不保存哈希、Gist ID、账号或 token。

准备工作

本地安装需要：

Node.js
Windows PowerShell，或 macOS/Linux 的 curl

启用 GitHub Gist 同步还需要 GitHub CLI gh：

# Windows
winget install GitHub.cli

# macOS
brew install gh

Linux 安装方式见 https://github.com/cli/cli/blob/trunk/docs/install_linux.md。

无需提前创建 Gist，也无需手工生成 Personal Access Token。设置向导会调用 GitHub CLI 的浏览器登录流程，并请求 Gist 权限。

第一台机器

1. 安装配置

Windows PowerShell：

irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.ps1 | iex

macOS / Linux：

curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.sh | sh

安装器先完成以下工作：

从公开 Gitea 仓库下载默认 zed-settings-sync.json。
把当前 Zed 配置备份到 backups/bootstrap-<时间>。
安装设置、键位、Tasks 和同步脚本。
创建空的机器本地同步状态。

这四步不访问 GitHub。没有 gh、没有登录或没有 Gist 都不会造成安装失败。

2. 连接 GitHub

安装结束时可以选择立即运行向导。稍后操作时：

重启或 Reload Zed。
按 Mod+R 打开 Task Picker。
运行 Zed Settings: Set Up / Reconfigure Sync...。
如果尚未登录，终端会显示一次性代码并打开 GitHub 浏览器授权页面。

脚本按以下顺序选择凭据：

验证当前 GH_TOKEN / GITHUB_TOKEN，包括 Gist 权限。
环境 token 无效时，移除它们后验证 GitHub CLI 凭据存储。
都不可用时启动浏览器登录。

同步脚本本身不会读取、打印或保存 token。

3. 创建首个 Gist

登录后向导会搜索当前账号下包含 zed-settings-sync.json 的 Gist。第一台机器通常没有结果：

选择 N. Create a new Secret Gist from this machine。
向导创建 Secret Gist 并上传当前 Zed 设置。
Gist ID 和当前 SHA-256 被记录到本机 scripts/settings-sync.json。
自动同步保持默认关闭，除非明确选择开启。

Secret Gist 不会出现在公开列表或搜索中，但知道链接的人仍可读取它。

新机器

安装 Node.js；需要同步时再安装 gh。
执行与第一台机器相同的一行安装命令。
运行 Set Up / Reconfigure Sync...。
使用同一个 GitHub 账号完成浏览器登录。
向导会自动列出已有的 Zed 设置 Gist；通常只有一个，直接选择即可。
初始同步方向选择 P. Pull remote settings onto this machine。
Pull 前默认安装产生的本地配置会被再次备份，然后替换为云端设置。
Reload Zed。

只有在使用其他账号、别人共享的 Gist 或自动发现失败时，才需要选择 M 并粘贴 Gist URL/ID。

日常手动同步

推荐默认使用手动同步，方向明确：

修改设置、键位、Tasks、代码片段或主题后，在当前机器运行 Push Now。
切换到另一台机器后运行 Pull Now。
不确定状态时先运行 Show Sync Status。

快捷键：

键位	操作
`Mod+; U`	Push Now
`Mod+; D`	Pull Now
`Mod+R`	打开 Task Picker

Push 发现远端已经变化时会显示本地、远端和同步基线哈希，并在覆盖前确认。Pull 发现本地已经变化时同样确认，并始终先创建备份。

自动同步

运行 Zed Settings: Enable Automatic Sync：

验证已经配置 Gist。
验证 GitHub CLI 的系统凭据存储，而不是依赖临时环境 token。
安装当前用户级的 15 分钟定时任务。
把 auto_sync 写为 true。

关闭时运行 Disable Automatic Sync，它会删除对应的系统调度项并保留 Gist 关联和同步基线。

系统实现：

Windows：Task Scheduler，任务名 ZedSettingsSync。
macOS：LaunchAgent cool.okk.zed-settings-sync.plist。
Linux：systemd user timer；没有 systemd 时使用带 # zed-settings-sync 标记的 crontab。

自动同步只处理方向明确的单边变化：

本地	远端	基线	结果
相同	相同	任意	无操作
已变	等于基线	存在	自动 Push
等于基线	已变	存在	备份后自动 Pull
已变	已变	存在	冲突，停止
不同	不同	不存在	无基线，停止

冲突、无基线、认证失效和网络错误不会触发覆盖。相同错误只通知一次，详细记录写入：

Windows: %APPDATA%\Zed\logs\settings-sync.log
macOS/Linux: ~/.config/zed/logs/settings-sync.log

日志超过 1 MB 后保留最多三份历史文件。

冲突恢复

Show Sync Status 可能显示：

状态	含义	建议
`synchronized`	本地和远端一致	无需操作
`local-changed`	只有本地变化	Push Now
`remote-changed`	只有远端变化	Pull Now
`conflict`	两边都变化	先 Export JSON，再决定保留哪一边
`no-baseline`	机器没有可靠同步基线	检查内容后手动 Push 或 Pull
`remote-missing`	Gist 中缺少同步文件	重新配置或手动 Push

发生冲突时不要连续试 Push/Pull。先运行 Export JSON... 保存本机单文件；需要保留远端时执行 Pull，需要保留本机时执行 Push。两个方向在覆盖前都会再次确认。

导入、导出与备份

Export JSON... 和 Import JSON... 会打开系统文件选择器。导出的 JSON 与 Gist 中的格式完全相同，顶层键直接是文件路径，例如：

{
  "settings.json": "...",
  "keymap.json": "...",
  "tasks.json": "..."
}

没有 files 外壳，也没有内置哈希。Import 不会覆盖本机保存的 Gist ID、自动同步设置或上次同步哈希，但导入后的内容会被识别为新的本地变化。

Import 和 Pull 的备份目录：

Windows: %APPDATA%\Zed\backups\sync-import-<时间>
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>

修改文件排除规则

编辑：

Windows: %APPDATA%\Zed\scripts\file-exclusions.json
macOS/Linux: ~/.config/zed/scripts/file-exclusions.json

defaults：始终排除的 Zed 默认规则。
custom：按 Alt+Shift+- 切换的自定义规则。

修改后先测试显隐，再运行 Push Now。其他机器 Pull 后会取得相同规则。

故障排查

Task 没有反应

新版 Setup、Status、Push、Pull、启用和禁用自动同步都会打开并保留终端。先查看终端中的完整错误；确认 Zed 已 Reload，且 Task 名称不是旧版的 Configure GitHub Gist。

环境 token 导致认证异常

脚本会先验证环境 token。无效时会自动回退到凭据存储，并在终端说明。若希望清理环境变量，可检查系统、Shell Profile 和 Zed 的 terminal env 设置。

GitHub 已登录但不能访问 Gist

运行 Set Up / Reconfigure Sync...。向导会调用 gh auth refresh --scopes gist 补充权限。

自动同步一直认证失败

后台任务不能依赖只存在于某个终端进程中的 GH_TOKEN。重新运行设置向导并完成浏览器登录，让 gh 把凭据保存到系统凭据存储，然后重新启用自动同步。

Pull 后没有立即生效

先运行 Show Sync Status 确认哈希一致，再执行 Mod+; K Reload Zed。某些扩展和 UI 状态仍可能需要完整重启。

更换或删除 Gist

运行 Set Up / Reconfigure Sync... 重新选择、输入或创建 Gist。切换成功后会建立新的同步基线。删除远端 Gist 前建议先 Export JSON。

7.8 KiB Raw Permalink Blame History Unescape Escape