CloudSound 二次开发记录：把 YesPlayMusic 改造成更适合展示的桌面端 Web 音乐应用

CloudSound 二次开发记录：把 YesPlayMusic 改造成更适合展示的桌面端 Web 音乐应用

今天这轮工作，核心不是继续“铺新页面”，而是把一个已经能运行的开源播放器项目，真正整理成一个更适合展示、讲解和后续继续开发的版本。

项目基于 qier222/YesPlayMusic 二次开发，我们把它整理成了自己的 CloudSound，并围绕“桌面端功能增强 + 工程整理 + 可展示文档输出”推进了一整轮工作。

一、今天这轮工作的边界

一开始我们确实尝试过移动端和 iPad 端适配，也做了一部分调整，但回过头看，这部分结果还不够稳定，离“可以作为成果展示”还有距离。

所以这次博客不再把移动端适配作为已完成成果，而是只展示今天真正稳定落地、可以拿得出手的三类 PC 端功能增强：

• 缓存管理增强
• 本地播放历史与听歌统计
• 播放器内嵌均衡器与音质入口

这个收口其实很重要。做项目时，最怕把“尝试过”写成“做成了”。技术博客也一样，真实比夸张更有价值。

二、项目最初为什么不好跑

这类二次开发项目看起来像“拉下来直接启动就行”，实际上环境坑很多。

今天最开始遇到的典型问题有：

1. Node.js 版本敏感

YesPlayMusic 这类老一些的 Vue 2 项目，对 Node 版本要求比较苛刻。版本太高时，依赖链和构建脚本都容易出问题。

2. 依赖完整性问题

仅仅把前端依赖装上，并不代表项目就能正常工作。播放器、Electron、构建链、代理 API 都可能成为问题点。

3. 前端能打开，不等于项目可用

项目是“前端 Web 应用 + 本地/独立 API 代理 + 本地缓存存储”的组合。页面能显示，只说明壳子起来了，不代表核心功能真的能用。

4. Git 分支和仓库展示也会踩坑

后面推 GitHub 的时候也遇到了一个很典型的问题：项目完整内容其实已经推上去了，只是推到了 master，而 GitHub 默认显示的是 main，结果网页上看起来像“推送失败”。

这件事也提醒我，工程整理不只是代码，Git 分支管理也属于工程质量的一部分。

三、今天真正完成的 3 组功能

1. 缓存管理增强

这一块的目标不是“加个按钮”，而是让缓存系统变得更可理解。

现在设置页里可以更清楚地看到：

• 缓存总量
• 各类缓存占用
• 每类缓存条目数
• 按分类清理缓存
• 刷新缓存统计

同时，我们还避免了一个很关键的问题：清理缓存时不再误伤本地听歌统计数据。

这意味着缓存清理不再是“粗暴一把删”，而是更接近一个真实播放器产品里的可维护功能。

2. 本地播放历史与听歌统计

这是这轮开发里我认为最有产品味的一部分。

我们新增了：

• 本地播放历史
• 听歌总时长
• 总播放次数
• 总歌曲数统计
• 最近播放记录
• 本地历史 / 云端历史切换

这类功能有个很明显的优点：不依赖额外远端服务，也能形成自己的本地数据沉淀。

对于个人项目、课程项目、毕设展示来说，这种“用户行为被记录并可视化”的能力，往往比单纯改几个页面更能体现产品思考。

3. 播放器内嵌均衡器与音质入口

相比把音质和均衡器埋在设置页里，我们把它们更贴近播放器本体，直接放进了播放器区域。

这一步的意义在于交互路径更合理：

• 设置页适合放全局偏好
• 播放器适合放播放过程中高频使用的音频控制能力

均衡器部分不仅仅是一个 UI 面板，还接入了实际播放链路，支持：

• 均衡器开关
• 多组预设
• 10 段手动调节
• 重置为默认值

同时，音质切换入口也一起内嵌到了播放器里，整体操作更顺手。

四、这轮工作里做对的几件事

1. 没把移动端半成品硬写成成果

移动端适配确实尝试了，也暴露出不少问题，但它现在还不到可以拿出来当“完成项”展示的程度。

所以这次 README 和博客都统一回收到了桌面端稳定成果上，这是很必要的。

2. 功能展示图改成了真实运行截图

之前如果继续用旧图，或者拿移动端图硬撑，会让成果展示和实际完成情况不一致。

这次重新整理后，README 和博客里的图都换成了当前版本运行时生成的 PC 端功能图，口径统一，也更真实。

3. 项目文档开始成体系

除了功能本身，这次还把几类文档补齐了：

• README
• LICENSE
• 开源归因文档
• 本地部署记录
• 技术博客

这些内容放在一起，项目才算真正有了“可交付”的感觉。

五、目前还没完成的部分

今天我们也顺手推进了移动端和 iPad 端适配，但结论很明确：

• 做过尝试
• 有一部分调整
• 但现在还不稳定
• 暂时不适合作为已完成成果展示

后面这一块会继续打磨，但应该被单独当成下一阶段任务，而不是混进这次已经完成的成果里。

六、这轮工程实践的收获

我觉得今天最大的收获，不只是“多了几个功能”，而是开始学会怎么把一个开源项目二次开发成自己的版本。

这里面真正重要的事情其实包括很多层：

• 跑通环境
• 调整依赖
• 区分前端、API 和本地存储的职责
• 给功能找对交互位置
• 让 Git 分支和仓库展示一致
• 把成果整理成 README 和博客

这些事情连起来，才是一轮完整的软件工程实践。

七、下一步怎么做

下一阶段更合适的方向不是再继续堆新功能，而是继续把已有改动打磨扎实。

我认为后面最值得推进的是：

• 继续修正移动端与 iPad 端适配
• 进一步梳理播放器桌面端视觉一致性
• 优化本地数据看板的表现形式
• 继续沉淀更清晰的开发文档

八、结语

今天这轮工作，CloudSound 至少已经从“把开源项目拉下来改了点东西”，走到了“有自己方向的桌面端增强版本”。

它还没有完全变成一个成熟产品，但已经开始有属于自己的功能重点、交互思路和工程整理方式了。这一步本身就很重要。