从 2.x 升级到 3.x 有哪些变化：老用户迁移注意清单

从 2.x（最后版本 2.9.0，2018 年）直接跳到 3.x 的老用户，中间隔了六年开发停顿加一次大版本迁移。这篇把需要知道的变化按四条线理清，帮你做升级决定与迁移准备。

一条时间轴先垫底

2.9.0（2018-03，最后 2.x）→ 六年空窗 → 3.0「Castaway」（2024-04，Qt5/KF5）→ 3.1（2024-08，Last.fm 令牌认证）→ 3.2（2024-12，Qt5/Qt6 双构建）→ 3.3（2025-07，Qt6/KF6 + GStreamer 引擎）→ 3.3.x 修复线延续至今。各版本的完整叙述见 二十年版本演进史。

界面：熟悉又陌生

• 三分格局没变：媒体源、上下文视图、播放列表的骨架与 2.x 一致——肌肉记忆大体有效；
• 上下文视图的 applet 有增减：相似艺人 applet 在 3.0 缺席、3.1 回归；当前曲目 applet 从 3.2 起默认显示（管理上下文 applet）；
• 部分默认值变了：暂停/停止淡出默认关闭（3.1.1 起）——觉得「怎么按暂停不对劲」的先去设置看看。

脚本：断层最大的一块

这是老用户最痛的一线，官方公告反复强调：

• 脚本框架从 QtScript 迁往 QJSEngine，迁移期旧 2.x 脚本大多不兼容；
• 脚本商店下载功能一度禁用；
• 脚本 API 文档部分过时。

依赖 2.x 脚本工作流的人（尤其歌词脚本重度用户）迁移前要有心理准备：3.x 初期的脚本生态在重建中，细节见 脚本系统。

格式与引擎：一收一放

• 收：RealMedia 与 Audible 支持移除（3.3）；部分 Last.fm 电台功能清理（3.3）；
• 放：cue 文件支持部分恢复（3.3）；数据库字符集升级——emoji 等极端字符正常入库（3.3）；「按缺标签筛选」（3.2）；
• 引擎统一：ReplayGain、可视化等特性从「看 Phonon 后端运气」变成全员统一可用（3.3）——这是升级后最先该重新验证的功能面（ReplayGain 是什么）。

数据与迁移：重点在此

• 收藏数据：3.x 有自己的数据库，首次启动按 怎么建立本地音乐收藏 重新指定目录扫描——音乐文件本身不动，只是重新索引；
• 统计与评分：不想从零攒统计的，用配置里的统计导入把旧数据带过来（评分与播放统计）；
• 歌单文件：m3u 等播放列表文件照常导入；3.1 对多格式存取做过一轮修复，跨版本歌单兼容性比早期好；
• Last.fm 老用户：收听记录在服务端，重连账号（3.1 起令牌认证）后记录无损接上（Last.fm 配置）。

升级前的三个动作

1. 备份配置与数据目录——唯一不可再生的是统计与评分；
2. 记下 2.x 的自定义项：改过的快捷键、装过的脚本、调过的布局——3.x 里按清单重建；
3. 接受不完美：官方自己说 3.0 时「不是每个特性都被充分测试」——遇到问题先升级小版本再看 故障排查。

值不值得升？对绝大多数人：值得——六年积累的修复、统一的引擎、活跃的维护（3.x 复活后已连发十余个版本），以及官方预告的 Amarok 4 也在 3.x 的技术底座上。留在 2.x 的唯一理由是某个 2.x 独有脚本依赖——而这正是社区正在重建的东西。