桌面端安装与本地开发
本文说明 Hydrogen Music 桌面版的安装入口、开发环境准备、双进程启动方式及桌面发行构建的已验证配置。
目的与范围
面向希望运行、调试或打包 Windows、macOS、Linux 桌面应用的开发者。本文聚焦根目录的 npm 脚本、Electron 主进程入口和 electron-builder 配置；Android 独立工程见 Android 开发说明，播放器功能、更新服务和 MPV 内部实现不在本页展开。README 的安装与开发章节 给出了实际操作顺序。
概览
用户安装时从项目 Releases 选择对应平台的安装包；Arch Linux 另有 AUR 包。开发者使用 Node.js 20.19.0+ 或 22.12.0+ 与 npm，先安装依赖，再分别启动 Vite 前端服务和 Electron。桌面入口由 package.json 的 main: background.js 指定；打包则先执行 Vite 构建，再交给 scripts/build.js。这些职责分别可见于 README、package.json。
架构
Sources: package.json, background.js, electron-builder.config.cjs
开发链路中 npm run dev 对应 Vite，npm start 对应由 nodemon 执行的 Electron；这是两个独立命令而非由单个脚本同时启动。package.json 发行链路的 dist 脚本调用 scripts/build.js，但本页没有读取该脚本实现，因此不推断它如何将配置交给 electron-builder。上图配置与输出的关系仅表示配置声明的目标目录，而非已经验证的构建脚本内部调用。
安装与开发流程
获取发行版
README 指向 Releases 下载入口，并列出 Windows 的 NSIS、Portable、Zip，macOS 的 DMG，以及 Linux 的 AppImage、Deb、RPM。对于 Arch Linux，文档给出以下独立安装方式：
yay -S hydrogen-music-binSource: README.md
首次使用建议登录网易云账号；README 明确提示某些功能依赖账号权限、VIP 权益或第三方服务登录状态。这是功能使用前提，不是启动 Electron 的硬性前提。README
准备依赖并分别启动两个终端
README 指定 Node.js 版本门槛和下面的命令顺序；每段代码均直接摘自该文件。先执行：
npm ciSource: README.md
终端一运行：
npm run devSource: README.md
终端二运行：
npm startSource: README.md
开发时主窗口使用 http://localhost:5173/，桌面歌词窗口使用 http://localhost:5173/desktop-lyric.html；内置网易云 API 服务默认使用本地 36530 端口。这些地址在 README 中明确列出。需要同时运行两端，才能为开发态的 Electron 窗口提供页面。
Sources: README.md, package.json, background.js
npm ci 会执行项目声明的 postinstall 脚本 node scripts/patch-ncm-api.cjs；脚本的补丁细节未从实现核实，不应把它描述为可选步骤。package.json
脚本与发行配置
npm 入口
| 命令 | 实际脚本 | 用途 |
|---|---|---|
npm run dev | vite | 启动前端开发服务 |
npm start | nodemon --exec electron . --watch ./ --ext js,vue,html,css,json | 用 nodemon 启动并监视桌面应用 |
npm run build | vite build | 单独生成前端构建产物 |
npm run preview | vite preview | 预览前端构建 |
npm run dist | vite build && node scripts/build.js -p never | 前端构建后执行桌面构建脚本 |
npm run _dist | vite build && node scripts/build.js -p always | 前端构建后以不同的 -p 值执行同一脚本 |
表中脚本原文见 package.json。-p never 和 -p always 的语义取决于未读取的 scripts/build.js，这里仅记录传参，不推断发布行为。下面是仓库中的原始配置摘录：
1"dev": "vite",
2"build": "vite build",
3"preview": "vite preview",
4"postinstall": "node scripts/patch-ncm-api.cjs",
5"start": "nodemon --exec electron . --watch ./ --ext js,vue,html,css,json",
6"_dist": "vite build && node scripts/build.js -p always",
7"dist": "vite build && node scripts/build.js -p never"Source: package.json
start 的监视范围和文件扩展名由此脚本直接约束；是否覆盖所有项目文件变更，不应超出该参数推断。
electron-builder 的打包边界
配置文件 将 background.js、两个 HTML 入口、dist/**/*、src/electron/**/* 及共享设置文件纳入 files；同时排除如 release、图片目录、字体和部分依赖附带文件。NODE_MODULE_PRUNE_DIRS 和 NODE_MODULE_PRUNE_FILE_PATTERNS 会继续生成依赖目录排除模式，但许可证、NOTICE 等文件由 onNodeModuleFile 匹配保留，详见 配置实现 与 文件过滤。
| 配置项 | 类型 | 取值／默认配置 | 作用 |
|---|---|---|---|
productName | string | Hydrogen Music | 桌面应用产品名称 |
appId | string | com.hydrogenmusic.app | 构建应用标识 |
asar | boolean | true | 启用 asar 打包 |
compression | string | maximum | 压缩设置 |
electronLanguages | string[] | en, en-US, zh_CN, zh_TW, zh-CN, zh-TW | 包含所列 Electron 语言资源 |
asarUnpack | string[] | **/node_modules/ffmpeg-static/** | 在 asar 外保留该依赖匹配内容 |
directories.output | string | release/${version} | 构建产物目录模板 |
nsis.oneClick | boolean | false | NSIS 非一键安装 |
nsis.allowToChangeInstallationDirectory | boolean | true | 允许更改安装目录 |
数值直接来自 electron-builder 配置。已读取的 macOS 部分声明 dmg target、图标和 getMpvExtraResourcesForPlatform('darwin')；Windows 与 Linux 的具体配置字段未在本页读到，因此格式列表仅采用 README 的声明。electron-builder.config.cjs README
可选 HiFi 本地输出使用 MPV；普通在线播放和默认本地播放无需 MPV。下载已构建的本机平台资源可使用仓库命令：
npm run mpv:downloadSource: README.md
其路径是 resources/mpv/<platform-arch>/；配置函数仅在对应平台目录存在时生成 extraResources 映射，因此缺少资源时该函数返回空数组，而不是在这里自动编译 MPV。README electron-builder.config.cjs