歌单 JSON 导出格式与手动编辑指南

为什么导出歌单

导出歌单除了跨设备同步，还有这些用途：

• 长期归档：怕 Gist 数据丢失或 GitHub 账号问题，可以把 JSON 文件存进自己的云盘或本地硬盘
• 批量编辑：用编辑器一次性重命名所有歌单、批量删除特定平台来源的歌曲
• 迁移到其他播放器：如果将来不用 Listen 1 了，JSON 文件里的歌曲名 + 歌手信息可以手动重新导入其他播放器
• 备份恢复：重装系统前导出，装完新系统后导入

JSON 导出文件格式

Listen 1 导出的歌单 JSON 大致结构如下：

{
  "exportVersion": 2,
  "exportTime": "2025-06-17T10:30:00+08:00",
  "playlists": [
    {
      "id": "local-1234567890",
      "name": "华语怀旧金曲",
      "coverUrl": "",
      "tracks": [
        {
          "name": "七里香",
          "artist": "周杰伦",
          "album": "七里香",
          "platformId": "netease",
          "sourceLink": "..."
        }
      ]
    }
  ],
  "favorites": [
    {
      "name": "晴天",
      "artist": "周杰伦",
      "platformId": "qq"
    }
  ]
}

关键字段说明：

手动编辑注意事项

删除歌曲

直接在 tracks 数组里删除对应的 JSON 对象即可。注意数组的逗号分隔符——删除中间的对象后，前一个对象末尾的逗号要保留，最后一个对象末尾不能有逗号。

重命名歌单

修改 name 字段即可。

添加新歌单

在 playlists 数组里新增一个完整的歌单对象，id 可以用时间戳生成：

{
  "id": "local-" + Date.now(),
  "name": "新歌单名称",
  "coverUrl": "",
  "tracks": []
}

编辑完成后保存为 UTF-8 编码的 JSON 文件，再导入 Listen 1。

导入 JSON 时的合并规则

导入时 Listen 1 的行为：

• 同名歌单：默认会跳过已存在的同名歌单（防止重复创建）
• ID 冲突：如果 JSON 里的歌单 ID 和本地已有 ID 相同，覆盖更新
• 新歌单：全部添加到「创建的歌单」列表末尾
• 收藏歌曲：追加到现有收藏列表，不重复的歌曲才会添加

JSON 文件的编码要求

Listen 1 使用 UTF-8 编码存储 JSON。如果用 Windows 记事本编辑，保存时确认编码是「UTF-8」而不是「ANSI」。ANSI 编码可能导致中文歌曲名乱码。

推荐使用 VS Code、Notepad++、Sublime Text 等现代编辑器，默认 UTF-8 无需担心。

导出 vs Gist 备份