purp1e/zed-sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13cf327f484c00e7e47a2c9bf87269a45836362e
zed-sync/SYNC-MANUAL.zh-CN.md
T

7.5 KiB
Raw Blame History

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

  1. 登录 GitHub，打开 https://gist.github.com/。
  2. 创建一个 Secret Gist。GitHub 不允许创建完全空白的 Gist，可以先放一个 README.md。
  3. 复制完整 Gist URL 或末尾的 Gist ID。

Gist ID 不是访问令牌。身份认证由 GitHub CLI gh 管理。

Secret Gist 只是不出现在公开搜索中，获得链接的人仍然可以读取其内容。同步 JSON 不包含 API Key，但仍应妥善保管 Gist URL。

3. 主机器首次上传

3.1 安装和认证 GitHub CLI

当前 Windows 机器已经安装 gh。其他机器可以使用系统包管理器安装：

winget install GitHub.cli

macOS：

brew install gh

安装后，在 Zed 中按 Mod+R 打开 Task Picker，运行：

Zed Settings: Authenticate GitHub...

也可以在终端执行：

gh auth login

3.2 保存 Gist

  1. 按 Mod+R。
  2. 运行 Zed Settings: Configure GitHub Gist...。
  3. 粘贴 Gist URL 或 Gist ID。
  4. 运行 Zed Settings: Push to GitHub Gist。
  5. 运行 Zed Settings: Show GitHub Gist Status，确认状态为 Synchronized。

Push 只会在该 Gist 中创建或更新 zed-settings-sync.json，不会删除 Gist 中的其他文件。

Gist ID 和上次同步哈希保存在本机：

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 仓库本身不保存设置或凭据，只需要包含：

bootstrap-from-gist.ps1
bootstrap-from-gist.sh

因此这个仓库可以公开；真正的设置仍只存放在指定 Gist 中。

4.2 一行安装

Windows PowerShell：

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

macOS/Linux：

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

迁移到其他 Gitea 仓库时，Raw URL 的常见形式是：

irm https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.ps1 | iex

curl -fsSL https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.sh | sh

执行过程中脚本会：

  1. 检查 Node.js 和 gh。
  2. 在尚未登录时运行 gh auth login。
  3. 询问 Gist URL 或 ID。
  4. 从 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 目录并运行：

.\install.ps1

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 格式：

Zed Settings: Export JSON...
Zed Settings: Import JSON...

两个命令都会弹出系统文件选择窗口。直接 Import 不会修改已保存的 Gist ID 和上次同步哈希；导入内容会被视为新的本地变化，可以随后 Push 到 Gist。

8. 修改文件排除规则

只编辑本机配置中的 custom 数组：

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

修改后按 Alt+Shift+- 测试显隐，再 Push 到 Gist。其他机器 Pull 后会取得相同规则。

9. 备份位置

每次 Import 或 Pull 前的备份位于：

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 会重新确认覆盖方向。

Reference in New Issue View Git Blame Copy Permalink