企业官网建设流程全解析

• 桌面应用
• 音视频

Mineradio 2.2.0 是当前仓库标记的历史稳定正式版本，本次发布说明围绕四条主线展开：更换下载入口、修复音乐接口的登录与账号识别、改善歌单加载与搜索分页、新增粒子预设与手势操作。本文以 docs/RELEASE_NOTES_v2.2.0.md 为骨架，结合仓库内对应源码与测试用例，逐条还原这些修复背后的实现机制，并给出从下载、校验、安装到升级验证的完整实操流程，帮助读者（包括 Agent 与 LLM）准确理解该版本的技术边界与可用能力。

一、版本概览：2.2.0 到底修复了什么

发布说明原文的变更要点共四条，均可在仓库源码中找到对应实现：

1. 下载入口已更换：旧收藏失效，须使用公告中的新网盘链接；同步体现在 README.md 的下载入口表格与 docs/RELEASE_NOTES_v2.2.0.md 内嵌的mineradio-download-page标记中。
2. 修复音乐接口的登录、账号识别与播放稳定性问题：对应 kugou-api.js 中的会话凭证解析、登录态分类与备用重试域名，以及 11-provider-fallback.js 中的播放源回退与音质降级重试。
3. 改善歌单加载、搜索分页，以及网络异常后的恢复：对应 07-search.js 的多平台分页游标，以及 09-queue-snapshot-autoplay.js 的播放快照恢复。
4. 新增粒子预设与更多手势操作，改善日常播放体验：对应 00-preset-archive-data.js 中的预设档案，以及 00-gesture-control.js 中的完整手势动作集。

需要明确的前提：根据 README.md 顶部声明，该项目目前处于长期停更状态，2.2.0 是历史稳定版本；本文所有技术描述均以当前仓库实际代码为准。

二、下载、校验与安装：从发布说明到可运行安装包

2.1 官方下载入口与识别要点

发布说明明确要求"使用公告中的新网盘链接，并更新旧收藏"，完整安装包文件名为Mineradio-2.2.0-Setup.exe。两条官方线路（夸克盘、百度云）同时登记在 docs/RELEASE_NOTES_v2.2.0.md 与 README.md 的下载表格中；文档尾部还以 HTML 注释形式保留了供更新页面解析的机器可读标记：

<!-- mineradio-download-page: 夸克盘|https://pan.quark.cn/s/4b124d3e81d3 --> <!-- mineradio-download-page: 百度云|https://pan.baidu.com/s/17CwpHUza67w_Grgc3s5nOw?pwd=SJHP -->

这两个标记与 docs/UPDATE_DELIVERY.md 描述的更新机制直接相关：软件主检测接口成功时，会显示 Release 正文前四条说明，并读取mineradio-download-page标记中的网盘线路作为下载入口。也就是说，2.2.0 的更新公告、README 和软件内更新入口共用同一组新链接，旧地址不再作为本次版本的下载入口。

2.2 完整性校验：SHA-256

发布说明给出了安装包的 SHA-256 摘要：

8fd318283bab2fe98190f7b879ede423dd8274a0aeec8d321570b8d022d4f989

建议下载完成后在 PowerShell 中校验后再安装：

Get-FileHash .\Mineradio-2.2.0-Setup.exe -Algorithm SHA256

比对输出与上列摘要一致再运行安装。README 同时提醒：不要误把.blockmap、latest.yml或win-unpacked目录当作正式安装包——正式分发以Mineradio-2.2.0-Setup.exe为准，安装包会创建桌面快捷方式。

2.3 安装包与latest.yml的分工

README.md 与 docs/UPDATE_DELIVERY.md 还界定了版本元数据文件docs/update/latest.yml的职责：它只记录版本号和发布时间，不填写files、path、url或sha512等安装包下载字段，由维护者以latest.yml名称上传到对应 Release，而不是使用打包工具生成的安装更新清单。这一设计使旧客户端在 GitHub API 访问失败时仍能通过备用线路发现更新。注意：该文件是给更新检测使用的元数据，不是安装包。

三、音乐接口修复：登录、账号识别与播放稳定性

发布说明第一条技术修复是"音乐接口的登录、账号识别与播放稳定性问题"。以仓库中的酷狗接口实现 kugou-api.js 为证据，可以从三个层面还原其含义。

3.1 登录态识别：从 Cookie 解析账号与 token

kugou-api.js提供了完整的会话凭证解析链路：

• parseCookieString/kugouCookieObject：把原始 Cookie 字符串切分为键值对象；
• extractKugouAuth：从 Cookie 中提取userid、token等字段（兼容token/Token/t/T/kugoo.token等多种键名），并基于mineradio-kugou:<userid|token>生成内部身份指纹；
• playbackReady = !!(userid && userid !== '0' && token)：只有同时存在有效 userid 与 token 才判定"登录可用"。

这就是"账号识别"问题的核心：如果登录态丢失、Cookie 过期或 token 字段名变化，playbackReady会退化为false，播放请求就会被导向登录提示，而不是直接失败。

3.2 错误分类与提示：区分登录、会员与网络问题

kugou-api.js 在播放地址请求失败时会对原始错误信息做正则归类：

} else if (/登录|token|login|会话|凭证/i.test(rawMessage)) { category = 'login_required'; } else { category = auth && auth.playbackReady ? 'vip_required' : 'login_required'; }

即：凡是命中"登录/token/会话/凭证"关键词的报错归类为login_required；未命中关键词时，如果登录态就绪则归类为vip_required（VIP 权益不足），否则仍归为login_required。这一分类驱动了前端"去登录 / 开通会员 / 换源重试"等差异化提示，是"登录稳定性"修复的可见表现。

3.3 播放稳定性：备用域名重试与源回退

稳定性层面有两层保障：

• 接口级重试：kugou-api.js 定义了备用播放信息域名KUGOU_PLAY_WEB_RETRY = 'https://wwwapiretry.kugou.com/play/songinfo'，主线路失败时切到重试线路；
• 源级回退：11-provider-fallback.js 统一处理"该源没有返回可播放地址"的场景，提示可能是版权、地区、会员或网络限制，并支持"换源或稍后重试"。QQ 音乐路径还实现了qqPlaybackRetryQualities：在请求音质失败后，从候选质量池中剔除失败档位，用兼容音质重新发起播放，同时保留断点续播位置（resumeAt）与启动自播进度（pendingPlaybackResumeAt）。

对应测试 kugou-api-resilience.test.js 与 playback-source-fallback-transaction.test.js 覆盖了请求异常注入与回退事务等场景，可作为验证上述行为的入口。

四、歌单加载、搜索分页与网络异常恢复

4.1 多平台搜索分页

发布说明提到"改善……搜索分页"，07-search.js 是这一能力的直接实现。其核心是按平台维护独立分页游标：

• searchMusicRenderState.providerPages保存每个平台各自的翻页状态；
• 每个平台有独立的单页数量上限：pageLimitByProvider = { netease: 18, qq: 12, kugou: 12, qishui: 12, spotify: 10 }；
• 判定是否还有下一页的规则（fetchMusicSearchResults）：

var hasMore = value.hasMore === true; if (value.hasMore == null) hasMore = songs.length >= requestedLimit; if (!songs.length || nextOffset <= offset) hasMore = false;

即：平台明确返回hasMore时以其为准；未返回时用"返回数量达到请求上限"推断；一旦没有新歌或游标未前进则关闭分页。聚合层searchProviderPagesHaveMore只要任一平台还有更多就允许继续"加载更多"。这一设计避免了某一平台翻到底就整体停住的问题，对应测试 search-frontend-pagination.test.js。

4.2 播放快照恢复：网络异常后的续听

"网络异常后的恢复"由 09-queue-snapshot-autoplay.js 承担：播放过程中会持久化最近一次播放快照（当前歌曲、队列、当前索引与播放进度）。启动时readLastPlaybackSnapshot读取快照并做两层处理：

• 通过hydrateCustomCover还原自定义封面等对象引用；
• 计算pendingPlaybackResumeAt = startupResumeSecondsFromSnapshot(snapshot)得到恢复播放位置，并在恢复失败时用applyRestoredPlaybackProgressUi先把 UI 进度还原到快照位置。

配合播放源回退（见上文 3.3），即使某次播放因网络中断失败，下次启动也能回到原队列与原进度附近，这正是"网络异常后恢复"的用户可见效果。

4.3 歌单加载

歌单加载链路分布在播放模块的多个文件中（如 02-playlist-detail.js、内置歌单库 built-in-playlist-library.js），与搜索分页共用同一套"平台游标 + 失败标记"的加载策略：providerPages[provider]在失败时写入{ hasMore: false, failed: true }，保证某个平台歌单拉取失败不会阻塞整个歌单列表的渲染。

五、新增粒子预设：13 个预设与用户存档体系

"新增粒子预设"在 00-preset-archive-data.js 中有完整清单，presetMeta数组定义了 13 个预设，presetDisplayOrder决定面板展示顺序：

其中 9–12 号被标记为premiumVisual: true并带专属强调色（如月蚀圣环accent: '#e8c98d'、雨幕霓虹accent: '#67efff'），展示顺序把 premium 预设排在面板最前。presetIcons为每个预设提供独立的 SVG 图标，面板按presetDisplayOrder = [0, 9, 10, 11, 12, 6, 7, 8, 5, 4, 2, 1, 3]排列。

预设并非写死的静态档位：USER_FX_ARCHIVE_STORE_KEY = 'mineradio-user-fx-archives-v1'表明用户可保存多份视觉参数存档；USER_FX_SHARE_PREFIX = 'MR2'、USER_FX_SHARE_PAYLOAD_TYPE = 'ufa'等常量则定义了用户预设的导出分享格式（支持 GZIP 压缩编码与 JSON 明文编码、增量/全量两种压缩粒度）。存档快照会归一化preset、intensity、cinemaShake、depth、coverResolution、bloomStrength等数百个视觉参数，并兼容歌词颜色预设（lyricColorPresets内置 18 种颜色）。此外，normalizeFxArchiveSnapshot中还包含一个兼容逻辑：旧存档preset === 3（虚空）在视觉预设 schema 不匹配时会被映射到5（星河），避免旧档位失效。视觉参数的归档、导出与校验测试见 curated-visual-presets.test.js 与 visual-performance-controls.test.js。

六、手势操作：从捏合旋转到播放控制

发布说明提到的"更多手势操作"在 00-gesture-control.js 中有完整实现。该模块基于 MediaPipe Hands 的 21 个手部关键点，把"摄像头手势"同时映射为粒子视觉交互与播放器控制两套动作。

6.1 手势与粒子视觉交互

实现细节：关键点先经 EMA 平滑（HAND_SMOOTH_ALPHA = 0.35），并对摄像头画面做 X 轴镜像；旋转角速度被限制在PARTICLE_SPIN_MAX = 6.2内，累计旋转角超过Math.PI * 10时自动归位（rebaseParticleRotationIfNeeded），避免浮点精度漂移。

6.2 手势与播放器控制

播放器动作在捏合/握拳之外独立判定，classifyGesturePlayerPose负责姿态分类：

动作都有独立的判定参数与防抖逻辑：候选手势需保持到hold时长才触发（触发后有cooldown冷却）；音量调节在武装（arm）后以 80ms 节流应用。三类灵敏度档位由gestureSensitivityProfile提供：

6.3 性能与生命周期

手势推理是显式开启的能力，识别可靠性优先（gestureModelComplexity固定返回 1），但推理频率会随性能档位限流：high/ultra档约 42ms 一帧、balanced约 55ms、其余 72ms。摄像头启动前会先通过桌面桥接请求摄像头权限（requestGestureCameraPermission），失败时提示在 Windows 隐私设置中开启，并把fx.cam持久化为off以避免反复启动失败。窗口隐藏、模态框打开、输入框聚焦、进度条拖动等场景会暂停播放器手势（gesturePlayerActionsAllowed），仅保留粒子视觉手势。对应生命周期测试见 gesture-runtime-lifecycle.test.js、gesture-camera-permission.test.js 与 gesture-player-actions.test.js。

七、从旧版升级与安装后的验证步骤

针对 2.1.0 及更早版本用户，docs/UPDATE_DELIVERY.md 记录了旧客户端更新入口的限制，升级 2.2.0 时可按以下流程操作：

1. 从 README.md 或发布公告的官方网盘入口下载Mineradio-2.2.0-Setup.exe；
2. 校验 SHA-256 是否为8fd318283bab2fe98190f7b879ede423dd8274a0aeec8d321570b8d022d4f989；
3. 已安装旧版的用户直接运行安装包即可完成覆盖更新（软件内更新入口只打开浏览器下载页，不会在客户端内下载或应用补丁）；
4. 若旧客户端没有弹出更新提醒：从托盘彻底退出并重新打开软件，切回普通窗口，等待约 30 秒后查看右上角更新箭头（2.1.0 在启动约 9 秒后仅检查一次、失败不自动重试、全屏/沉浸/桌面壁纸模式会隐藏标题栏箭头，因此看不到入口属于预期行为，不影响直接下载安装包升级）；
5. 浏览器或 SmartScreen 拦截未签名安装包时，按 README 的建议选择"保留/仍要运行"；若杀毒软件明确提示木马或已隔离，应删除文件重新从官方入口下载，不要强行运行；
6. 启动后验证：搜索多平台翻页（各平台独立继续加载）、网络中断后的续播恢复、Fx 面板中的新预设（月蚀圣环/雨幕霓虹/折光蝶群/深海绽放）以及摄像头手势的开关与灵敏度档位。

八、小结

Mineradio 2.2.0 的发布说明虽然只有四条要点，但在仓库源码中均有完整落地：登录与账号识别依赖 kugou-api.js 的凭证解析与错误分类，播放稳定性依赖备用域名与 11-provider-fallback.js 的源级回退，搜索分页与网络恢复依赖 07-search.js 与 09-queue-snapshot-autoplay.js，视觉与交互升级集中在 00-preset-archive-data.js 与 00-gesture-control.js。下载与校验信息以 docs/RELEASE_NOTES_v2.2.0.md 和 README.md 为准，更新交付机制详见 docs/UPDATE_DELIVERY.md。该版本作为当前仓库标注的历史稳定版本，其实现细节对研究 Electron 音乐播放器的多源回退、分页聚合与手势交互具备直接的参考价值。

• 桌面应用
• 音视频