在音乐流媒体服务日益普及的今天，Spotify 用户积累了大量的播放列表，这些播放列表往往通过文件夹进行层次化管理。然而，当用户需要备份或迁移这些精心组织的音乐收藏时，面临一个严峻的技术挑战：Spotify Web API 不提供文件夹层次结构访问。这意味着传统的 API 调用只能获取扁平的播放列表列表，而宝贵的组织结构和协作元数据将丢失。
问题背景：层次结构缺失的数据备份困境
大多数 Spotify 数据备份工具，如 Exportify 和 spotify-backup，都依赖于 Spotify Web API。这些工具能够导出播放列表的基本信息和曲目列表，但存在一个根本性缺陷：它们无法获取用户精心组织的文件夹层次结构。正如 mikez 在 spotify-folders 项目中指出的："The Spotify Web API does currently not support getting the folder hierarchy."
这种限制导致备份数据失去了原有的组织逻辑。想象一下，一个用户将播放列表按 "季节"、"情绪"、"活动" 等维度分类，每个文件夹下又有子文件夹，这种复杂的树状结构在传统备份中会被扁平化为一个无序列表。更糟糕的是，协作播放列表的元数据 —— 包括描述、关注者数量、协作状态 —— 虽然可以通过 API 获取，但与层次结构分离后，其上下文意义大打折扣。
技术挑战：缓存提取与 API 限制的平衡
1. 本地缓存：层次结构的唯一来源
由于 Web API 的限制，获取文件夹层次结构的唯一可行方案是从 Spotify 本地客户端缓存中提取。这一方法的核心挑战在于：
- 缓存格式不透明：Spotify 不公开缓存格式规范，开发者需要通过逆向工程解析数据结构
- 跨平台差异：不同操作系统的缓存位置和格式存在差异
- macOS:
~/Library/Application Support/Spotify - Windows:
%APPDATA%\Spotify - Linux:
~/.config/spotify
- macOS:
- 技术变更风险：2023 年 11 月 30 日，Spotify 更改了缓存存储技术，导致 spotify-folders 等项目需要完全重写代码
2. 缓存解析的技术实现
spotify-folders 项目展示了从缓存提取层次结构的基本方法。其核心逻辑是：
# 简化的缓存解析逻辑
def extract_folder_hierarchy(cache_path):
# 1. 定位缓存文件（格式可能为SQLite、LevelDB或其他）
# 2. 解析文件夹和播放列表的关联关系
# 3. 构建树状数据结构
# 4. 序列化为JSON格式
关键的技术细节包括：
- 缓存文件定位：需要处理不同操作系统和 Spotify 版本的文件路径差异
- 数据格式解析：Spotify 可能使用 protobuf、JSON、或自定义二进制格式
- 关系重建：从扁平的数据表中重建树状层次结构
3. Web API 的补充作用
虽然 Web API 不提供层次结构，但它对于获取播放列表元数据至关重要。通过GET /playlists/{playlist_id}端点，可以获取：
- 基本元数据：名称、描述、封面图片
- 协作信息：
collaborative字段标识是否为协作播放列表 - 统计信息：关注者数量、曲目数量
- 所有权信息：创建者 ID 和显示名称
数据结构设计：完整序列化方案
要实现播放列表层次结构的完整导出，需要设计一个既能保持嵌套关系，又能包含丰富元数据的数据结构。以下是推荐的 JSON 格式：
{
"export_version": "1.0",
"export_timestamp": "2025-12-21T10:30:00Z",
"user_id": "spotify:user:example",
"root": {
"type": "folder",
"name": "Root",
"uri": "spotify:user:example:folder:root",
"children": [
{
"type": "folder",
"name": "Seasons",
"uri": "spotify:user:example:folder:f0dcb1c2b1a98521",
"children": [
{
"type": "playlist",
"name": "Summer Vibes",
"uri": "spotify:playlist:37i9dQZF1DXdCsscAsbRNz",
"metadata": {
"description": "The perfect summer playlist",
"collaborative": false,
"followers": 1250,
"public": true,
"owner": {
"id": "spotify:user:creator123",
"display_name": "Music Lover"
},
"tracks_count": 50,
"snapshot_id": "MTU5NjY0NzIwMCwwMDAwMDAwMCwwMDAwMDAwMCwwMDAwMDAwMA=="
},
"tracks": [
{
"added_at": "2025-06-15T08:30:00Z",
"added_by": "spotify:user:creator123",
"track": {
"id": "spotify:track:7GhIk7Il098yCjg4BQjzvb",
"name": "Blinding Lights",
"artists": ["The Weeknd"],
"album": "After Hours"
}
}
]
}
]
}
]
}
}
关键设计决策
- 混合数据源：层次结构来自本地缓存，元数据来自 Web API
- URI 作为唯一标识：使用 Spotify URI 确保跨平台一致性
- 版本控制：包含导出版本和时间戳，便于后续迁移和兼容性处理
- 完整元数据：保留所有可通过 API 获取的信息，包括协作状态和关注者统计
工程实现：跨平台兼容性与离线同步
1. 跨平台兼容性策略
由于缓存位置和格式的差异，实现跨平台兼容需要分层设计：
class SpotifyCacheExtractor:
def __init__(self):
self.platform = self.detect_platform()
self.cache_path = self.get_cache_path()
def detect_platform(self):
import platform
system = platform.system()
if system == "Darwin":
return "macos"
elif system == "Windows":
return "windows"
elif system == "Linux":
return "linux"
else:
raise UnsupportedPlatformError(f"Unsupported platform: {system}")
def get_cache_path(self):
if self.platform == "macos":
return os.path.expanduser("~/Library/Application Support/Spotify")
elif self.platform == "windows":
return os.path.join(os.getenv("APPDATA"), "Spotify")
elif self.platform == "linux":
return os.path.expanduser("~/.config/spotify")
2. 缓存格式适配层
考虑到 Spotify 可能随时更改缓存格式，需要设计可扩展的解析器：
class CacheFormatAdapter:
def __init__(self):
self.parsers = {
"sqlite": SQLiteParser(),
"leveldb": LevelDBParser(),
"protobuf": ProtobufParser(),
"custom_binary": CustomBinaryParser()
}
def parse(self, cache_data):
# 自动检测格式并选择相应的解析器
format_type = self.detect_format(cache_data)
parser = self.parsers.get(format_type)
if parser:
return parser.parse(cache_data)
else:
raise UnsupportedFormatError(f"Unsupported cache format: {format_type}")
3. 离线同步与增量备份
对于需要频繁备份的用户，实现增量同步至关重要：
- 快照比较：使用播放列表的
snapshot_id检测变更 - 增量导出：只导出自上次备份以来发生变化的播放列表
- 冲突解决：处理本地缓存与云端状态不一致的情况
- 版本历史：保留多个版本的备份，支持回滚
4. 性能优化参数
处理大量播放列表时，性能成为关键考虑因素：
# 配置参数示例
performance:
batch_size: 50 # API调用的批处理大小
rate_limit_delay: 100 # 毫秒，避免触发速率限制
cache_ttl: 3600 # 缓存有效期（秒）
max_retries: 3 # API失败重试次数
timeout: 30 # API调用超时时间（秒）
export:
include_tracks: true # 是否包含曲目详情
max_tracks_per_playlist: 10000 # 单个播放列表最大曲目数
compress_output: true # 是否压缩输出文件
split_large_exports: true # 是否分割大型导出
split_threshold_mb: 100 # 分割阈值（MB）
风险与限制
1. 技术依赖风险
- 缓存格式变更：Spotify 可能随时更改缓存格式，导致工具失效
- API 限制：Web API 有速率限制，大量播放列表导出需要分批次处理
- 认证过期：OAuth 令牌需要定期刷新，长期备份需要自动化处理
2. 数据完整性限制
- 编辑历史丢失：无法获取播放列表的完整编辑历史
- 协作详情缺失：无法获取协作播放列表的具体协作者列表
- 隐私设置影响：私有播放列表的元数据可能受限
3. 法律与合规考虑
- 服务条款：需要确保工具使用符合 Spotify 服务条款
- 数据隐私：用户数据需要妥善处理，避免泄露
- 版权限制：导出的数据仅限个人使用，不得用于商业目的
实践建议与最佳实践
1. 定期备份策略
- 频率：建议每月进行一次完整备份
- 存储：使用云存储和本地存储双重备份
- 验证：定期验证备份文件的完整性和可读性
2. 迁移准备
- 格式转换：准备将备份数据转换为其他音乐服务的格式
- 测试迁移：在实际迁移前进行小规模测试
- 回滚计划：制定迁移失败时的回滚方案
3. 监控与告警
- 工具健康检查：监控备份工具的运行状态
- 变更检测：设置 Spotify API 或缓存格式变更的告警
- 备份成功率：跟踪备份成功率和失败原因
未来展望
随着用户对数据自主权的需求增长，音乐流媒体服务可能会提供更完善的数据导出功能。理想情况下，Spotify 应该提供：
- 官方层次结构 API：通过 Web API 直接获取文件夹结构
- 完整数据导出：支持一键导出所有用户数据，包括播放历史、推荐算法等
- 标准化格式：采用行业标准的数据交换格式
- 增量同步 API：支持高效的数据同步，减少带宽消耗
结论
Spotify 播放列表层次结构的完整导出是一个复杂但可行的工程挑战。通过结合本地缓存提取和 Web API 调用，可以构建一个既能保持嵌套关系，又能保留丰富元数据的备份方案。关键的成功因素包括：
- 分层架构设计：分离缓存解析、API 调用和数据序列化
- 跨平台兼容性：处理不同操作系统的差异
- 错误恢复机制：处理 API 失败、缓存格式变更等异常情况
- 用户友好性：提供清晰的配置选项和进度反馈
虽然存在技术限制和风险，但通过精心设计和持续维护，用户可以有效地保护自己精心组织的音乐收藏，为可能的服务迁移或长期存档做好准备。
资料来源：
- mikez/spotify-folders GitHub 项目：从本地 Spotify 缓存提取文件夹层次结构
- Spotify Web API 文档：Get Playlist 端点获取播放列表元数据
- Exportify 项目：基于 Web API 的播放列表导出工具