Tauon Music Box与Jellyfin音乐库导入故障分析与解决方案

问题背景

Tauon Music Box作为一款跨平台音乐播放器，支持通过Jellyfin媒体服务器导入音乐库。近期用户反馈在v7.8.3版本中出现连接测试成功但音乐导入失败的异常情况，控制台日志显示存在KeyError: 'Size'的错误。

技术分析

错误本质

从日志堆栈追踪可见，程序在t_jellyfin.py模块的439行尝试访问MediaSources数组第一个元素的Size属性时触发异常。这表明：

1. Jellyfin API返回的媒体元数据中缺少预期的Size字段
2. 程序未对字段缺失情况做防御性处理

版本差异现象

值得注意的是：

• 相同问题同时出现在AUR和Flatpak两种打包方式中
• 升级到git版本后问题消失
• Jellyfin服务端版本为10.10.3.0时复现

解决方案

临时解决方案

对于v7.8.3版本用户，可通过以下方式规避：

1. 手动检查Jellyfin媒体文件的元数据完整性
2. 确保所有音轨文件包含完整的媒体信息

永久解决方案

建议升级到最新开发版本（git版本），该版本已包含：

1. 更健壮的Jellyfin API响应处理逻辑
2. 对缺失字段的容错机制
3. 改进的媒体元数据解析流程

技术启示

该案例展示了客户端开发中常见的接口兼容性问题：

1. 服务端API可能随版本演进改变数据结构
2. 客户端应实现完善的错误处理和降级机制
3. 跨版本测试的重要性

最佳实践建议

1. 定期更新客户端以获取兼容性修复
2. 复杂媒体库导入前建议先备份数据
3. 关注服务端与客户端的版本兼容性矩阵