256 lines
7.8 KiB
Markdown
256 lines
7.8 KiB
Markdown
# Zed 设置同步使用手册
|
||
|
||
本方案使用 GitHub Gist 中的单个 `zed-settings-sync.json` 同步 Zed 设置。JSON 顶层直接保存各配置文件的路径和完整内容；SHA-256 只在运行时计算，不写入同步文件。
|
||
|
||
## 1. 同步内容
|
||
|
||
会同步：
|
||
|
||
- `settings.json`：界面、字体、主题、编辑器行为及扩展自动安装清单。
|
||
- `keymap.json`：自定义键位。
|
||
- `tasks.json`：文件显隐和设置同步任务。
|
||
- `scripts/` 中的文件显隐及同步脚本。
|
||
- 非空的 `snippets/` 和 `themes/` 目录。
|
||
|
||
不会同步：
|
||
|
||
- GitHub 登录凭据、API Key 和系统环境变量。
|
||
- 本机保存的 Gist ID 和上次同步哈希。
|
||
- Zed 数据库、缓存、聊天记录、项目文件及扩展二进制。
|
||
|
||
扩展 ID 位于 `settings.json` 的 `auto_install_extensions` 中。导入后由 Zed 在目标平台重新安装扩展。
|
||
|
||
## 2. 准备 Gist
|
||
|
||
不需要预先创建 Gist：第一次执行 Push 时，如果本机尚未配置 Gist，系统会询问是否自动创建新的 Secret Gist。
|
||
|
||
已有 Gist 时，也可以登录 GitHub、打开 <https://gist.github.com/>，复制完整 Gist URL 或末尾的 Gist ID，再通过 `Configure GitHub Gist...` 关联。
|
||
|
||
Gist ID 不是访问令牌。身份认证由 GitHub CLI `gh` 管理。
|
||
|
||
Secret Gist 只是不出现在公开搜索中，获得链接的人仍然可以读取其内容。同步 JSON 不包含 API Key，但仍应妥善保管 Gist URL。
|
||
|
||
## 3. 主机器首次上传
|
||
|
||
### 3.1 安装和认证 GitHub CLI
|
||
|
||
当前 Windows 机器已经安装 `gh`。其他机器可以使用系统包管理器安装：
|
||
|
||
```powershell
|
||
winget install GitHub.cli
|
||
```
|
||
|
||
macOS：
|
||
|
||
```sh
|
||
brew install gh
|
||
```
|
||
|
||
安装后，在 Zed 中按 `Mod+R` 打开 Task Picker，运行：
|
||
|
||
```text
|
||
Zed Settings: Authenticate GitHub...
|
||
```
|
||
|
||
也可以在终端执行：
|
||
|
||
```sh
|
||
gh auth login
|
||
```
|
||
|
||
### 3.2 创建或关联 Gist
|
||
|
||
1. 按 `Mod+R`。
|
||
2. 没有 Gist 时直接运行 `Zed Settings: Push to GitHub Gist`，确认自动创建。
|
||
3. 已有 Gist 时先运行 `Zed Settings: Configure GitHub Gist...` 并粘贴 URL/ID，再执行 Push。
|
||
4. 运行 `Zed Settings: Show GitHub Gist Status`，确认状态为 `Synchronized`。
|
||
|
||
Push 只会在该 Gist 中创建或更新 `zed-settings-sync.json`，不会删除 Gist 中的其他文件。
|
||
|
||
Gist ID 和上次同步哈希保存在本机：
|
||
|
||
```text
|
||
Windows: %APPDATA%\Zed\scripts\settings-sync.json
|
||
macOS/Linux: ~/.config/zed/scripts/settings-sync.json
|
||
```
|
||
|
||
此文件不参与导入导出，所以其他机器不会覆盖当前机器记录。
|
||
|
||
## 4. 新机器首次接入
|
||
|
||
第一次接入只需要运行仓库里的独立 bootstrap 脚本。它会询问 Gist URL/ID，直接读取 Gist 单 JSON，再安装全部设置和同步工具；不需要下载或解压便携目录。
|
||
|
||
### 4.1 安装前置程序
|
||
|
||
新机器需要：
|
||
|
||
- Zed 或 ZedG。
|
||
- Node.js。
|
||
- GitHub CLI `gh`。
|
||
|
||
bootstrap 仓库本身不保存设置或凭据，只需要包含：
|
||
|
||
```text
|
||
bootstrap-from-gist.ps1
|
||
bootstrap-from-gist.sh
|
||
```
|
||
|
||
因此这个仓库可以公开；真正的设置仍只存放在指定 Gist 中。
|
||
|
||
### 4.2 一行安装
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.ps1 | iex
|
||
```
|
||
|
||
macOS/Linux：
|
||
|
||
```sh
|
||
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.sh | sh
|
||
```
|
||
|
||
迁移到其他 Gitea 仓库时，Raw URL 的常见形式是：
|
||
|
||
```powershell
|
||
irm https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.ps1 | iex
|
||
```
|
||
|
||
```sh
|
||
curl -fsSL https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.sh | sh
|
||
```
|
||
|
||
执行过程中脚本会：
|
||
|
||
1. 检查 Node.js 和 `gh`。
|
||
2. 在尚未登录时运行 `gh auth login`。
|
||
3. 询问 Gist URL 或 ID；留空时自动创建新的 Secret Gist。
|
||
4. 输入已有 Gist 时从 GitHub API 读取配置；留空时使用本仓库的 `zed-settings-sync.json` 种子配置。
|
||
5. 验证顶层文件路径，防止写出 Zed 配置目录。
|
||
6. 备份新机器已有配置。
|
||
7. 安装设置、键位、Tasks、snippets、themes 和辅助脚本。
|
||
8. 保存 Gist ID 和远端整文件 SHA-256 作为首次同步基线。
|
||
|
||
安装完成后重启 Zed，运行 `Zed Settings: Show GitHub Gist Status`，状态应为 `Synchronized`。
|
||
|
||
为了降低执行远程脚本的供应链风险，可以把 URL 中的 `main` 换成审核过的 commit SHA。bootstrap 仓库不应加入访问令牌或其他秘密。
|
||
|
||
### 4.3 便携目录备用安装
|
||
|
||
不能访问 Raw URL 时，仍可复制完整 `zed-config-portable` 目录并运行：
|
||
|
||
```powershell
|
||
.\install.ps1
|
||
```
|
||
|
||
```sh
|
||
sh ./install.sh
|
||
```
|
||
|
||
然后在 Task Picker 中认证 GitHub、配置 Gist 并执行首次 Pull。
|
||
|
||
## 5. 之后的日常使用
|
||
|
||
开始在一台机器工作前：
|
||
|
||
1. 按 `Mod+R`。
|
||
2. 运行 `Zed Settings: Show GitHub Gist Status`。
|
||
3. 如果显示 `Remote changes available`，执行 Pull。
|
||
|
||
修改设置、键位、Tasks、排除规则或 snippets 后：
|
||
|
||
1. 执行 Push。
|
||
2. 确认状态变为 `Synchronized`。
|
||
3. 再到其他机器执行 Pull。
|
||
|
||
常用快捷键：
|
||
|
||
| 快捷键 | 操作 |
|
||
|---|---|
|
||
| `Mod+R` | 打开 Task Picker |
|
||
| `Mod+; U` | Push 到 Gist |
|
||
| `Mod+; D` | 从 Gist Pull |
|
||
| `Mod+; K` | Reload Zed |
|
||
|
||
`Mod` 在 Windows/Linux 是 Ctrl，在 macOS 是 Command。
|
||
|
||
## 6. 哈希和冲突处理
|
||
|
||
系统比较三个 SHA-256：
|
||
|
||
- 当前机器实时生成的单 JSON 哈希。
|
||
- Gist 中单 JSON 的哈希。
|
||
- 当前机器上次成功 Push/Pull 时保存的哈希。
|
||
|
||
Status 可能显示：
|
||
|
||
| 状态 | 含义 | 建议操作 |
|
||
|---|---|---|
|
||
| `Synchronized` | 本地和 Gist 一致 | 无需操作 |
|
||
| `Local changes pending upload` | 只有本机有变化 | Push |
|
||
| `Remote changes available` | 只有 Gist 有变化 | Pull |
|
||
| `Conflict` | 本机和 Gist 都有变化 | 先导出本地备份，再决定 Push 或 Pull |
|
||
| `Not synchronized on this machine` | 这台机器尚无同步基线 | 首次接入通常选择 Pull |
|
||
|
||
Push 覆盖远端前、Pull 覆盖本地前都会显示哈希并要求确认。Pull 会自动备份本地配置；系统不会尝试逐字段自动合并。
|
||
|
||
## 7. 离线 JSON 导入导出
|
||
|
||
不使用 Gist 时，也可以使用完全相同的单 JSON 格式：
|
||
|
||
```text
|
||
Zed Settings: Export JSON...
|
||
Zed Settings: Import JSON...
|
||
```
|
||
|
||
两个命令都会弹出系统文件选择窗口。直接 Import 不会修改已保存的 Gist ID 和上次同步哈希；导入内容会被视为新的本地变化，可以随后 Push 到 Gist。
|
||
|
||
## 8. 修改文件排除规则
|
||
|
||
只编辑本机配置中的 `custom` 数组：
|
||
|
||
```text
|
||
Windows: %APPDATA%\Zed\scripts\file-exclusions.json
|
||
macOS/Linux: ~/.config/zed/scripts/file-exclusions.json
|
||
```
|
||
|
||
修改后按 `Alt+Shift+-` 测试显隐，再 Push 到 Gist。其他机器 Pull 后会取得相同规则。
|
||
|
||
## 9. 备份位置
|
||
|
||
每次 Import 或 Pull 前的备份位于：
|
||
|
||
```text
|
||
Windows: %APPDATA%\Zed\backups\sync-import-<时间>
|
||
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
|
||
```
|
||
|
||
便携安装器产生的备份使用 `portable-install-<时间>` 名称。
|
||
|
||
## 10. 常见问题
|
||
|
||
### Task Picker 中没有 Zed Settings
|
||
|
||
重新运行一行 bootstrap 命令，或运行便携目录中的 `install.ps1` / `install.sh`，然后 Reload Zed。
|
||
|
||
### 提示找不到 gh
|
||
|
||
安装 GitHub CLI 后完全退出并重启 Zed，使编辑器读取更新后的 PATH。
|
||
|
||
### Gist 返回 404
|
||
|
||
检查 Gist URL/ID、当前 GitHub 账号以及 Gist 是否仍然存在。重新运行 `Configure GitHub Gist...` 可以更换记录。
|
||
|
||
### Gist 中没有 zed-settings-sync.json
|
||
|
||
先在已经配置好的主机器上执行一次 Push。
|
||
|
||
### Pull 后键位或界面没有立即变化
|
||
|
||
执行 `Mod+; K` Reload Zed；如果扩展仍在安装，等待完成后再重启一次。
|
||
|
||
### 换了另一个 Gist
|
||
|
||
运行 `Configure GitHub Gist...` 并输入新 ID。系统会保留新 ID，同时清空旧 Gist 对应的上次同步哈希，下一次 Push/Pull 会重新确认覆盖方向。
|