GitHub Gist 歌单备份完整流程

什么是 GitHub Gist 同步

Listen 1 提供了一个独特的同步方案：将本地歌单和收藏数据备份到 GitHub Gist。Gist 是 GitHub 提供的轻量级代码片段托管服务，每个 Gist 有唯一 ID，可以通过 API 读写。

为什么选 Gist：

免费：GitHub 账户自带，无需额外付费
可靠：GitHub 全球 CDN，数据不会丢
跨设备：任何设备登录同一 GitHub 账户就能同步
可回滚：Gist 自带版本历史，可以恢复任意时间点的歌单

第一步：GitHub 授权

在 Listen 1 设置 → 账号同步区域，找到「GitHub 授权」按钮
点击后浏览器跳转 GitHub 授权页面
用你的 GitHub 账号登录并确认授权
GitHub 返回 code 给 Listen 1 的回调地址
回到 Listen 1 界面，点击「已经完成授权」按钮
授权完成，Listen 1 获得读写 Gist 的权限

回调页面地址是 listen1.github.io/listen1/callback.html，授权成功后会提示「请返回插件页，点击『已经完成授权』按钮，完成授权过程」。

第二步：创建备份 Gist

授权完成后，Listen 1 会在你的 GitHub 账户下自动创建一个专用 Gist：

Gist 的描述会标注是 Listen 1 的歌单备份
包含几个 JSON 文件：歌单列表、收藏列表、播放历史（可选）
Gist 设为 Secret（私密），只有你和 Listen 1 能访问

第三步：手动备份

授权成功后，在「账号同步」区域：

一键备份：点击备份按钮，Listen 1 立即将当前本地全部歌单推送到 Gist
自动备份：部分版本支持开启「每 30 分钟自动备份」

第四步：从 Gist 恢复

换设备或重装 Listen 1 后：

同样用你的 GitHub 账号授权
Listen 1 检测到已存在的 Gist，会提示「检测到云端备份，是否恢复？」
点击恢复，歌单和收藏自动拉回到新设备

多设备同步流程

设备 A（桌面版）    GitHub Gist     设备 B（移动端）
     |                  |                |
     |--一键备份----->|                |
     |                  |<--授权----|
     |                  |--恢复------>|
     |                  |                |--看到同步的歌单

备份内容包含什么

Gist 备份的 JSON 结构：

playlists.json：你创建的全部歌单，包含每首歌的歌曲名、歌手、专辑、来源平台 ID
favorites.json：收藏的歌曲列表
fav_playlists.json：收藏的外部歌单
settings.json（可选）：部分用户设置（循环模式、默认音质等）

不会备份：各平台的登录 token（出于安全考虑）、播放历史、搜索历史。

手动查看备份 Gist

可以在 GitHub 个人主页的 Gists 标签页找到 Listen 1 的备份。文件名通常以 listen1_playlists_ 开头。

备份数据是纯 JSON 文本，可以直接下载查看或手动编辑（但编辑后需要重新导入 Listen 1）。

常见问题

授权失败

检查浏览器是否拦截了弹窗或跳转，GitHub 页面是否能正常访问。如果回调没回来，可以手动复制授权码到 Listen 1 的输入框。

备份冲突

如果在两台设备上同时修改了歌单并分别备份，后备份的会覆盖先备份的。建议在一台设备修改后立即备份，另一台设备先恢复再修改。

删除 Gist

在 GitHub 上手动删除 Listen 1 的备份 Gist 后，Listen 1 检测不到会提示重新创建。删除 Gist 前确保不需要恢复数据。