企业官网建设流程全解析

Mineradio 2.2.0 构建交付实战：安装包怎么打包，旧版本如何发现更新

【免费下载链接】Mineradio-paused一款以电影镜头、粒子视觉和歌词舞台为核心的沉浸式音乐播放器。项目地址: https://gitcode.com/gh_mirrors/mi/Mineradio-paused

Mineradio 是一款 Windows 桌面沉浸式音乐播放器，2.2.0 是它的当前正式版本。这篇实战指南沿一个版本的生命周期，讲清 Mineradio 安装包构建与更新交付：交付哪些资产、从源码怎么打包出安装包、旧版本如何发现更新、用户从哪下载、安全如何兜底。

📦 交付什么：版本边界与资产契约

先回答"交付的是什么"。RELEASE.md 用一组硬约束定死了本次发布的五个坐标：

构建上有两条红线：只从当前可信源码完整构建，不复用旧安装包或旧dist/产物；正式 Release 不混入 Mineradio_Beat 产物，保证单一产品线交付。

只上传两个文件，其余留在本地

GitHub Release 只附带两个文件：dist/Mineradio-2.2.0-Setup.exe安装包，和 docs/update/latest.yml 版本说明。后者的全部内容只有两行：

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

为什么这么"抠"？因为latest.yml是旧客户端的备用线路。manifest（版本说明文件）在主检测接口（GitHub Releases API）不可达时，靠它来发现新版本。只发安装包而漏掉它，备用链路就直接断了。

对应地，三类文件明确不上传：

1. blockmap（增量更新描述文件，记录文件块哈希，供更新时只取差异）；
2. 补丁文件；
3. electron-builder 生成的完整安装更新清单（带files/path/url/sha512等下载字段的清单）。

构建时产生的 blockmap、安装清单与校验记录只用于本地验收。安装包的 SHA-256 记录在 RELEASE.md 中：8fd318283bab2fe98190f7b879ede423dd8274a0aeec8d321570b8d022d4f989，发布前需与 docs/RELEASE_NOTES_v2.2.0.md 中的值逐位核对。

🏗️ 怎么交付：从源码到安装包的三条命令

构建的终点是一个能直接跑起来的桌面应用，玩家看到的启动页就是它：

三条命令的分工

构建入口在 package.json 的scripts字段，执行顺序固定：

1. npm install：安装 electron、electron-builder 等依赖；
2. npm start：等价于electron .，由主进程desktop/main.js加载本地服务，先确认能正常跑；
3. npm run build:win：执行electron-builder --win nsis，生成 Windows NSIS（Nullsoft Scriptable Install System，Windows 安装包脚本框架）安装包，产物输出到dist/。

另有两条辅助路径：build:win:dir生成免安装的win-unpacked目录；build:win:internal-beta用独立的 electron-builder.internal-beta.json 加--publish never构建内部测试包。

产物命名由build.nsis.artifactName一个字段决定：Mineradio-${version}-Setup.${ext}，代入版本号即Mineradio-2.2.0-Setup.exe。

安装器交互参数与本地可用的验收内容

NSIS 安装器的关键参数：oneClick: false表示向导模式（用户逐步点击，而非一键静默安装），perMachine: false表示按用户安装，allowToChangeInstallationDirectory: false固定安装目录，同时创建桌面与开始菜单快捷方式。

一个便于验收的细节：asar: false使包内源码不压缩，win-unpacked/resources/app是明文目录，人工核对正式版本号、资源完整性与源码一致性时可以直接打开看。

🔍 旧版本怎么知道：更新检测的四级降级链

四条线路按优先级依次降级

主检测逻辑集中在 server.js 的fetchLatestUpdateInfo。客户端向本地服务请求更新时，它按顺序尝试四条线路，前一条失败自动切下一条：

1. 本地/远端 manifest：若设置了MINERADIO_UPDATE_MANIFEST环境变量，优先读取该 JSON（支持本地文件路径或 HTTP 地址）。这条线路用于本地模拟线上 Release，验证整条更新链路；
2. 官方 Releases API：请求releases/latest端点，固定 8.5 秒超时。成功后解析 tag 名、发布页地址与正文（正文提供应用内入口的网盘标记与更新说明）；
3. 最小版本文件备用线路：API 失败时抓取latest.yml（每条线路 6.5 秒超时），解析出version与releaseDate，提示"发现新版本，请前往发布页面获取安装包"，点击后打开对应版本的发布页；
4. 本地兜底：全部失败时按当前版本返回updateAvailable: false，不误报新版本。

仓库坐标（owner/repo）配置在 package.json 的mineradio.update字段，并可用MINERADIO_UPDATE_REPOSITORY、MINERADIO_UPDATE_OWNER/REPO、MINERADIO_UPDATE_MIRRORS等环境变量覆盖。preferMirrors: true时，uniqueDownloadCandidates会为每条候选 URL 生成最多 6 条国内加速线路（镜像，即转发 GitHub 文件以加快国内访问的代理），并让镜像优先于直连。

2.1.0 旧客户端的固化限制

docs/UPDATE_DELIVERY.md 记录了 2.1.0 旧客户端的更新行为。这些限制固化在已安装客户端里，不能靠修改 Release 正文远程改变：

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

官方排查路径：从托盘彻底退出并重新打开软件，切回普通窗口，等待约 30 秒（网络慢则更久）查看右上角更新箭头；仍未出现时，直接用公告里的新网盘链接下载安装包。

🔗 用户从哪里下载：公告入口与机器可读的隐藏标记

同一组链接写在三处

本次下载入口更换为两条网盘线路：夸克盘与百度云（百度云链接把提取码SJHP放在 URL 查询参数里，写为?pwd=SJHP）。同一组链接出现在三处且必须一致：

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

旧分享地址不再作为本次版本的下载入口，用户需更新旧收藏。

mineradio-download-page 网盘链接隐藏标记怎么写

公告正文采用"人读文本 + 隐藏标记"双写法：可见文本面向用户，隐藏标记面向程序，且解析结果以隐藏标记为准，避免正文排版变化破坏机器可读性。隐藏标记是 HTML 注释，本次的两条标记写在 RELEASE.md 末尾：

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

服务端解析：标记优先、回退可见行、清洗与上限

解析入口是 server.js 的extractReleaseDownloadPages，流程三步：

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

每条 URL 还要先过safeExternalUpdateUrl安全校验：只接受https:协议（http:及其他协议一律返回空串）、长度上限 2048 字符、解析失败视为非法。tests/update-external-only.test.js 的第三条用例验证了这一点：四条标记中一条http://的不安全线路被过滤，仅三条 HTTPS 线路进入结果——即使正文被恶意或误写入非 HTTPS 链接，客户端也不会采用。

主检测成功时，应用内更新入口展示 Release 正文前四条说明与标记中的网盘线路，点击后由系统浏览器打开外部下载页。

🛡️ 安全如何兜底：客户端红线与测试固化

「软件内不下载安装包」的三道关卡

RELEASE.md 明确了一条边界：2.0.3+客户端不得从 Release assets 识别或下载安装包，软件内更新只读取正文中的网盘线路。也就是说，即使 Release 附带完整.exe，客户端也只把它当普通附件，不读取、不下载、不缓存、不应用，本地补丁下载与应用逻辑整体不存在。

这条策略落地为三道关卡：

1. 历史路由下线：/api/update/download与/api/update/patch两个旧路由统一返回UPDATE_EXTERNAL_ONLY错误与 410 状态码；
2. 渲染端再校验：00-update-preview.js 的openUpdateDownloadSource在打开前再次校验new URL(raw).protocol === 'https:'，然后调用window.desktopWindow.openUpdatePage(target)打开系统浏览器；界面文案明确提示"软件不会在本地下载或应用补丁"；
3. 主进程复核：desktop/main.js的mineradio-open-update-pageIPC 先验证可信窗口来源，再检查 URL 长度不超过 2048、协议为 https，最后才调用shell.openExternal。

测试如何阻止旧下载链路被重新引入

tests/update-external-only.test.js 的第二条用例用"断言缺席"防止本地下载链路复活：先断言 410 与UPDATE_EXTERNAL_ONLY存在，再断言startUpdateDownloadJob、startUpdatePatchJob、updateDownloadJobs、PATCH_ALLOWED、UPDATE_DOWNLOAD_DIR、pickPatchAsset等符号已从源码中消失；渲染端同样断言/api/update/download、openUpdateInstaller、「快速补丁」等字样不出现。

tests/update-download-link-rotation.test.js 覆盖「换链接」场景的正确性：新 Release 的两条标记替换旧的三条线路而不是追加（渲染层重置选中线路索引、清空旧公告文案）；显式的downloadPages优先于旧的externalUrl字段，旧链接不会混入新列表；显式传入空列表或非 HTTPS 列表时，旧线路退役，downloadPageUrl回退到发布页地址；不带downloadPages的旧式单页 manifest 仍保持兼容。

✅ 最后一道闸门：发布前验收与用户避坑

六步验收清单怎么做

RELEASE.md 要求发布前按序完成：

1. 运行完整回归检查与 Electron 启动检查：用 scripts/quick-check.js（对应 Windows 下的quick-check.bat），覆盖语法检查、多项回归测试、渲染模块解析、主窗口与打包守卫；加--electron参数（或quick-check.bat full）额外执行 Electron 运行时冒烟；
2. 构建并检查win-unpacked/resources/app内容，核对正式版本、资源完整性与源码一致性；
3. 验证安装包启动、退出、重启和用户数据恢复；
4. 确认仓库与安装包不含 Cookie、Token、凭据、缓存或本机日志；
5. 核对安装包 SHA-256；
6. 核对公告、README 与软件更新入口中的两条新网盘链接保持一致。

安装被拦截怎么办，旧包为什么废弃

未签名 Electron 安装包可能被浏览器、Windows Defender 或 SmartScreen 提示风险。处理顺序见 README.md：先确认文件来自公告入口且文件名是Mineradio-2.2.0-Setup.exe；浏览器下载列表选「保留」/「仍要保留」；SmartScreen 蓝色拦截窗口点「更多信息」→「仍要运行」。若杀毒软件明确报告木马或高危并已隔离，不要强行运行，删除后重新从公告网盘入口下载。

两个提醒：v1.0.10及更早的旧安装包不再建议继续安装或传播；.blockmap、latest.yml与win-unpacked目录都不是正式安装包。项目目前处于长期停更状态，2.2.0是历史正式版本，正式分发以Mineradio-2.2.0-Setup.exe为准。

总结

一个版本的旅程是一条链路：可信源码完整构建出Mineradio-2.2.0-Setup.exe，与最小latest.yml一起上传 GitHub Release；旧客户端经「本地 manifest → 官方 API → latest.yml → 本地兜底」四级降级感知新版本；最终由正文中的隐藏标记引导系统浏览器打开网盘页完成下载，而整条边界由测试与验收清单固定下来。

【免费下载链接】Mineradio-paused一款以电影镜头、粒子视觉和歌词舞台为核心的沉浸式音乐播放器。项目地址: https://gitcode.com/gh_mirrors/mi/Mineradio-paused