223 lines
7.8 KiB
Markdown
223 lines
7.8 KiB
Markdown
# Zed 设置同步手册
|
||
|
||
本方案把 Zed 的设置、键位、Tasks、文件排除规则、代码片段和主题整理为一个扁平的 `zed-settings-sync.json`，通过 GitHub Gist 在机器间同步。同步文件内部不保存哈希、Gist ID、账号或 token。
|
||
|
||
## 准备工作
|
||
|
||
本地安装需要：
|
||
|
||
- Node.js
|
||
- Windows PowerShell，或 macOS/Linux 的 `curl`
|
||
|
||
启用 GitHub Gist 同步还需要 GitHub CLI `gh`：
|
||
|
||
```powershell
|
||
# Windows
|
||
winget install GitHub.cli
|
||
```
|
||
|
||
```sh
|
||
# 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：
|
||
|
||
```powershell
|
||
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.ps1 | iex
|
||
```
|
||
|
||
macOS / Linux：
|
||
|
||
```sh
|
||
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.sh | sh
|
||
```
|
||
|
||
安装器先完成以下工作：
|
||
|
||
1. 从公开 Gitea 仓库下载默认 `zed-settings-sync.json`。
|
||
2. 把当前 Zed 配置备份到 `backups/bootstrap-<时间>`。
|
||
3. 安装设置、键位、Tasks 和同步脚本。
|
||
4. 创建空的机器本地同步状态。
|
||
|
||
这四步不访问 GitHub。没有 `gh`、没有登录或没有 Gist 都不会造成安装失败。
|
||
|
||
### 2. 连接 GitHub
|
||
|
||
安装结束时可以选择立即运行向导。稍后操作时：
|
||
|
||
1. 重启或 Reload Zed。
|
||
2. 按 `Mod+R` 打开 Task Picker。
|
||
3. 运行 `Zed Settings: Set Up / Reconfigure Sync...`。
|
||
4. 如果尚未登录，终端会显示一次性代码并打开 GitHub 浏览器授权页面。
|
||
|
||
脚本按以下顺序选择凭据：
|
||
|
||
1. 验证当前 `GH_TOKEN` / `GITHUB_TOKEN`，包括 Gist 权限。
|
||
2. 环境 token 无效时，移除它们后验证 GitHub CLI 凭据存储。
|
||
3. 都不可用时启动浏览器登录。
|
||
|
||
同步脚本本身不会读取、打印或保存 token。
|
||
|
||
### 3. 创建首个 Gist
|
||
|
||
登录后向导会搜索当前账号下包含 `zed-settings-sync.json` 的 Gist。第一台机器通常没有结果：
|
||
|
||
1. 选择 `N. Create a new Secret Gist from this machine`。
|
||
2. 向导创建 Secret Gist 并上传当前 Zed 设置。
|
||
3. Gist ID 和当前 SHA-256 被记录到本机 `scripts/settings-sync.json`。
|
||
4. 自动同步保持默认关闭，除非明确选择开启。
|
||
|
||
Secret Gist 不会出现在公开列表或搜索中，但知道链接的人仍可读取它。
|
||
|
||
## 新机器
|
||
|
||
1. 安装 Node.js；需要同步时再安装 `gh`。
|
||
2. 执行与第一台机器相同的一行安装命令。
|
||
3. 运行 `Set Up / Reconfigure Sync...`。
|
||
4. 使用同一个 GitHub 账号完成浏览器登录。
|
||
5. 向导会自动列出已有的 Zed 设置 Gist；通常只有一个，直接选择即可。
|
||
6. 初始同步方向选择 `P. Pull remote settings onto this machine`。
|
||
7. Pull 前默认安装产生的本地配置会被再次备份，然后替换为云端设置。
|
||
8. 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`：
|
||
|
||
1. 验证已经配置 Gist。
|
||
2. 验证 GitHub CLI 的系统凭据存储，而不是依赖临时环境 token。
|
||
3. 安装当前用户级的 15 分钟定时任务。
|
||
4. 把 `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 |
|
||
| 已变 | 已变 | 存在 | 冲突，停止 |
|
||
| 不同 | 不同 | 不存在 | 无基线，停止 |
|
||
|
||
冲突、无基线、认证失效和网络错误不会触发覆盖。相同错误只通知一次，详细记录写入：
|
||
|
||
```text
|
||
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 中的格式完全相同，顶层键直接是文件路径，例如：
|
||
|
||
```json
|
||
{
|
||
"settings.json": "...",
|
||
"keymap.json": "...",
|
||
"tasks.json": "..."
|
||
}
|
||
```
|
||
|
||
没有 `files` 外壳，也没有内置哈希。Import 不会覆盖本机保存的 Gist ID、自动同步设置或上次同步哈希，但导入后的内容会被识别为新的本地变化。
|
||
|
||
Import 和 Pull 的备份目录：
|
||
|
||
```text
|
||
Windows: %APPDATA%\Zed\backups\sync-import-<时间>
|
||
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
|
||
```
|
||
|
||
## 修改文件排除规则
|
||
|
||
编辑：
|
||
|
||
```text
|
||
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。
|