Mineradio 2.2.0 发布流程与更新交付架构：从 Release 边界、网盘分发到备用检测线路的完整实战指南

• 桌面应用
• 音视频

Mineradio 是一款 Windows 桌面沉浸式音乐播放器（融合桌面模式、歌词舞台、粒子视觉与 3D 歌单架），其 2.2.0 版本在 GitHub Release 上以「完整安装包 + 最小版本说明」的方式交付，并配合公告网盘入口完成下载分发。本文以仓库根目录的 RELEASE.md 为核心，结合 server.js 的更新检测实现、package.json 的构建配置与 tests/update-external-only.test.js 等测试用例，完整讲解 2.2.0 的发布边界、发布资产、网盘分发标记、客户端外部更新策略、备用检测线路以及发布前检查清单，帮助读者掌握这套「软件内不下载安装包、只引导外部网盘」的发布与更新机制。

一、发布边界：版本、Tag 与构建原则

RELEASE.md 首先定义了本次发布的硬性边界，所有后续操作都以这些约束为起点：

构建原则包含三条关键约束：

1. 仅从当前可信源码完整构建，不复用旧安装包或旧dist/产物；
2. 正式 Release 不混入 Mineradio_Beat 产物，保证单一产品线交付；
3. GitHub Release 只附带完整安装包与最小版本说明latest.yml，不上传 blockmap 或补丁文件。

其中「仅从可信源码完整构建」与 package.json 中的构建脚本形成对应关系：

npm install npm start npm run build:win

• npm start：Electron 主进程加载本地服务（主入口为 desktop/main.js）；
• npm run build:win：执行electron-builder --win nsis，生成 Windows NSIS 安装包，产物输出到dist/；
• 另有build:win:dir（生成免安装的win-unpacked目录）与build:win:internal-beta（使用独立配置文件 electron-builder.internal-beta.json 构建内部测试包）两条辅助脚本。

NSIS 安装包的产物命名规则定义在 package.json 的build.nsis.artifactName字段：Mineradio-${version}-Setup.${ext}，代入版本号后即得到Mineradio-2.2.0-Setup.exe。安装器为向导模式（oneClick: false、perMachine: false），并创建桌面与开始菜单快捷方式。

二、发布资产清单：安装包 + 最小 latest.yml

RELEASE.md 明确规定 GitHub Release 只上传两个文件：

• dist/Mineradio-2.2.0-Setup.exe（构建产物）
• docs/update/latest.yml（版本说明）

版本说明latest.yml只包含version与releaseDate两个字段，不得使用带安装包下载字段的构建工具清单。仓库中的 docs/update/latest.yml 实际内容为：

version: 2.2.0 releaseDate: '2026-09-07T03:56:08.000Z'

这一「最小化」设计有明确的兼容性动机：latest.yml供旧版客户端在主检测接口（GitHub Releases API）访问失败时作为备用线路使用。如果只发布安装包而不发布latest.yml，那么当旧客户端访问 GitHub API 失败时，将无法通过备用线路发现新版本（详见 docs/UPDATE_DELIVERY.md 开头说明）。

同时需要明确两个「不上传」与两个「本地验收」：

• 不上传blockmap（增量更新描述文件）与补丁；
• 不上传electron-builder 生成的完整安装更新清单（带files/path/url/sha512等下载字段的清单）；
• 构建生成的 blockmap、安装清单与校验记录只用于本地验收。

安装包校验值在 RELEASE.md 中给出：

SHA-256: 8fd318283bab2fe98190f7b879ede423dd8274a0aeec8d321570b8d022d4f989

该值也同步出现在 docs/RELEASE_NOTES_v2.2.0.md 中，发布前需逐项核对。

三、网盘分发：Release 正文中的隐藏下载标记

3.1 两条新网盘线路

2.2.0 的下载入口已更换，公告提供两条网盘线路（夸克盘与百度云，百度云带提取码SJHP），并要求用户更新旧收藏。本次下载入口同时出现在三处，且保持一致：

• 发布公告（Release 正文与 docs/RELEASE_NOTES_v2.2.0.md）；
• 仓库 README.md 的「立即下载」表格；
• 软件内更新入口。

3.2mineradio-download-page隐藏标记

RELEASE.md 要求Release 正文使用两条mineradio-download-page隐藏标记提供本次下载入口，并保留百度云链接中的提取码参数。标记以 HTML 注释形式写入正文，例如 docs/RELEASE_NOTES_v2.2.0.md 末尾的写法：

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

这种「隐藏标记 + 可见公告」双写法的价值在于：可见文本面向人类用户阅读，隐藏标记则面向客户端程序化解析，且解析结果以隐藏标记为准，避免正文排版变化破坏机器可读性。

3.3 服务端解析与安全约束

服务端解析逻辑位于 server.js 的extractReleaseDownloadPages（server.js）：

1. 先用正则匹配所有<!-- mineradio-download-page: 标签|URL -->形式的隐藏标记；
2. 若隐藏标记存在，直接采用；否则回退解析正文中可见的「夸克盘/百度云/蓝奏云/网盘：URL」格式行；
3. 结果交给normalizeUpdateDownloadPages（server.js）做标签清洗（去除<>|字符、截断到 24 字符）与去重，最多保留 6 条。

每条 URL 都要经过safeExternalUpdateUrl（server.js）的安全校验：

• 只接受https:协议，http:及其他协议一律返回空串；
• URL 长度上限 2048 字符；
• 解析失败视为非法。

测试 tests/update-external-only.test.js 专门验证了这一行为：四条标记中「http://example.com/file」的不安全线路被过滤，仅三条 HTTPS 线路进入结果。也就是说，即使 Release 正文被恶意或误写入非 HTTPS 链接，客户端也不会采用。

四、客户端更新策略：软件内不下载安装包

4.1 外部更新 Only

RELEASE.md 强调一条重要的客户端行为边界：2.0.3+客户端不得从 Release assets 识别或下载安装包，软件内更新只读取正文中的网盘线路。也就是说：

• 即使 Release 附带完整安装包（.exe），客户端也只把它当作普通 asset，不读取、不下载、不缓存、不应用；
• 应用内更新入口仅展示 Release 正文前四条说明与mineradio-download-page标记中的网盘线路，点击后通过系统浏览器打开外部下载页；
• 客户端不存在本地补丁下载与应用逻辑。

这一策略在 server.js 中体现为：/api/update/download与/api/update/patch两个历史路由被移除，统一返回UPDATE_EXTERNAL_ONLY错误与 410 状态码，且源码中不再包含startUpdateDownloadJob、updateDownloadJobs、PATCH_ALLOWED等下载/补丁 worker 相关实现。tests/update-external-only.test.js 的第二条用例逐一断言了这些符号的「存在」与「缺席」，防止本地下载链路被重新引入。

前端渲染侧位于 public/js/modules/08-account/00-update-preview.js：openUpdateDownloadSource(index)通过window.desktopWindow.openUpdatePage(target)打开选中的网盘线路，并在打开前再次校验new URL(raw).protocol === 'https:'；界面文案明确提示「软件不会在本地下载或应用补丁」。

4.2 更新检测的降级链路

服务端主检测逻辑集中在fetchLatestUpdateInfo（server.js），按以下顺序降级：

1. 本地/远端 manifest：若配置了MINERADIO_UPDATE_MANIFEST环境变量，优先读取该 JSON（支持本地文件路径或 HTTP URL，见readUpdateManifest，server.js），用于本地验证更新链路，可模拟线上 Release；
2. GitHub Releases API：请求https://api.github.com/repos/{owner}/{repo}/releases/latest（8.5 秒超时），解析tag_name、html_url、body（从中提取网盘标记与更新说明）；
3. latest.yml备用线路：API 失败时，请求https://github.com/{owner}/{repo}/releases/latest/download/latest.yml，由parseLatestYmlUpdateInfo（server.js）解析version/releaseDate，得到「发现新版本，请前往发布页面获取安装包」的通用提示，点击后打开对应版本的发布页；
4. 本地兜底：全部失败时返回localUpdateFallback（server.js），此时updateAvailable: false，不会误报新版本。

仓库与平台（owner/repo）的配置来自 package.json 的mineradio.update字段：

"mineradio": { "update": { "provider": "github", "owner": "XxHuberrr", "repo": "Mineradio", "preview": false, "preferMirrors": true, "mirrors": [ "https://gh.llkk.cc/", "https://ghfast.top/", "https://gh-proxy.com/" ] } }

readUpdateConfig（server.js）还会读取MINERADIO_UPDATE_REPOSITORY、GITHUB_REPOSITORY、MINERADIO_UPDATE_OWNER/REPO、MINERADIO_UPDATE_MANIFEST(_URL/_FILE)、MINERADIO_UPDATE_MIRRORS等环境变量覆盖配置。当preferMirrors为 true 时，uniqueDownloadCandidates（server.js）会为每条候选 URL 生成最多 6 个国内加速镜像线路，并让镜像线路优先于直连。

4.3 备用线路的兼容细节：2.1.0 的入口限制

docs/UPDATE_DELIVERY.md 记录了 2.1.0 旧客户端的更新行为，这些限制属于已安装客户端的固化行为，无法通过修改 Release 正文远程改变：

• 启动约 9 秒后检查一次；失败后没有自动重试；
• 检测成功后仅显示右上角更新箭头，不会自动弹出公告；
• 全屏、沉浸和桌面壁纸模式下，标题栏被隐藏，因此更新箭头也不可见；
• 打开更新面板不会重新发起检查。

排查更新入口时，官方建议的流程是：从托盘彻底退出并重新打开软件，切回普通窗口，等待约 30 秒后查看右上角更新箭头（网络较慢时需要更久）；仍未出现入口时，直接使用本次公告的新网盘链接下载完整安装包。这些行为同样体现在 README.md 的「使用说明」中：已安装旧版本的用户可直接运行Mineradio-2.2.0-Setup.exe完成更新。

4.4 链接轮换的正确性验证

tests/update-download-link-rotation.test.js 覆盖了「下载入口轮换」场景，验证了以下关键语义：

• 新 Release 正文中的两条mineradio-download-page标记会替换旧的三条线路，而不是追加（渲染层applyLatestUpdateInfo会重置selectedDownloadPageIndex，清空旧公告文案）；
• 显式提供的downloadPages列表优先于externalUrl旧字段，旧链接不会混入新列表；
• 显式传入空列表或非 HTTPS 列表时，旧线路被退役，downloadPageUrl回退到 Release 页面地址；
• 不带downloadPages的旧式单页响应仍保持兼容（兼容旧版 manifest）。

这套测试保证了「换链接」发布时，旧客户端不会把已失效的旧收藏地址当作新入口展示。

五、发布前检查清单：六步验收

RELEASE.md 给出了发布前必须完成的检查项，可按序执行：

1. 运行完整回归检查与 Electron 启动检查：仓库提供 scripts/quick-check.js（对应 Windows 下的 quick-check.bat），覆盖服务端符号完整性、构建配置、渲染模块引用、Electron 运行时冒烟等多项检查；
2. 构建并检查win-unpacked/resources/app内容：核对正式版本号、资源完整性与源码一致性（由于asar: false，resources/app为明文目录，便于人工核对）；
3. 验证安装包启动、退出、重启和用户数据恢复：覆盖安装、升级、重启等真实用户路径；
4. 确认仓库与安装包不含敏感数据：Cookie、Token、凭据、缓存或本机日志都不得进入产物——这也与 PRIVACY.md 的约定一致（登录 Cookie、搜索历史、自定义封面、节奏分析缓存等只保存在本机用户数据目录）；
5. 核对安装包 SHA-256：与8fd318283bab2fe98190f7b879ede423dd8274a0aeec8d321570b8d022d4f989逐位比对；
6. 核对公告、README 与软件更新入口中的两条新网盘链接：三处入口保持一致，旧分享地址不再作为本次版本的下载入口。

六、版本状态与下载安装注意事项

根据 README.md 的说明，Mineradio 项目当前处于长期停更状态，2.2.0是历史正式版本；本仓库保留公开源码、历史版本与下载说明，允许个人玩家 Fork、建立分支或制作二创版本。正式分发以Mineradio-2.2.0-Setup.exe为准，不要把.blockmap、latest.yml或win-unpacked目录当成正式安装包。v1.0.10及更早的旧安装包不再建议继续安装或传播，请使用本次公告提供的Mineradio-2.2.0-Setup.exe。

安装被浏览器、Windows Defender 或 SmartScreen 拦截时，应先确认文件来自公告入口且文件名正确，再按 README 中的步骤选择「保留/仍要保留」或「更多信息 → 仍要运行」；若杀毒软件明确报告木马或高危，不要强行运行，应删除后重新从公告网盘入口下载。

总结

Mineradio 2.2.0 的发布流程可以概括为一条清晰的链路：可信源码完整构建 → 生成Mineradio-2.2.0-Setup.exe→ 与最小latest.yml一起上传 GitHub Release → 正文写入两条mineradio-download-page网盘标记 → 客户端经 GitHub API 检测、latest.yml备用线路兜底、最终由浏览器打开外部网盘页完成下载。整套机制在 server.js 中落地、在 tests/update-external-only.test.js 与 tests/update-download-link-rotation.test.js 中被测试固化，并在 docs/UPDATE_DELIVERY.md 中记录了与 2.1.0 旧客户端的兼容约束。无论是想复刻这套「外部更新」分发方案，还是为二创版本规划发布流程，本文涉及的边界定义、资产清单、隐藏标记格式与验收清单都可以直接作为操作手册使用。

• 桌面应用
• 音视频