洛雪音乐桌面版使用指南：免费聚合多平台的开源 Electron 音乐播放器
【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop
晚上写代码时，你只记得一句副歌却想不起歌名，打开一个窗口同时搜遍几个音乐平台、挑音质最好的一版直接播，不用在多个 App 和会员之间来回切——洛雪音乐桌面版（lx-music-desktop）就是为此设计的。它基于 Electron 40 与 Vue 3 开发，采用 Apache-2.0 协议开源，覆盖 Windows、macOS、Linux 三大平台，当前最新版本为 v2.12.2。
🎯 核心能力：跨平台聚合搜索与播放
在搜索框输入歌名或歌手名，客户端会并行查询多个音乐源，把结果合并展示，你可以直接从中挑一首播放，无需关心它来自哪个平台。内置源涵盖酷我（kw）、酷狗（kg）、QQ 音乐（tx）、网易云（wy）、咪咕（mg）、虾米（xm）等，各源的接口封装位于 src/renderer/utils/musicSdk/。
几个和搜索直接相关的细节：
- 搜索支持模糊匹配与拼音（拼音数据见 src/common/utils/pinyin/），记不清完整歌名也能命中；
- 结果可显示来源标记（
list.isShowSource默认开启），方便你判断版本； - 默认播放质量为 128k，可在播放设置里调高；
- 播放列表、稍后播放、试听队列分开管理，支持多选批量操作。
💻 安装与首次运行
各系统的发布产物在打包脚本中均已定义（见 package.json），按平台挑选即可：
| 平台 | 可选安装包 | 说明 |
|---|---|---|
| Windows | 安装版 / 便携版 / 7z 绿色版，另有 Win7 专用版 | 便携版在程序目录创建portable文件夹即可数据随行 |
| macOS | DMG（x64 与 arm64 两种） | 拖入应用程序文件夹 |
| Linux | deb（amd64/arm64/armv7l）/ rpm / pacman / AppImage | 按发行版任选其一 |
数据目录约定：Linux 在~/.config/lx-music-desktop，macOS 在~/Library/Application Support/lx-music-desktop，Windows 在%APPDATA%/lx-music-desktop。首次启动建议先完成四件事：挑选稳定的接口源、选定窗口尺寸（默认 1114×718）、确认播放质量、按习惯改一遍全局快捷键。
想参与开发的话，环境要求 Node ≥ 22：
git clone https://gitcode.com/GitHub_Trending/lx/lx-music-desktop cd lx-music-desktop npm install npm run dev🎨 外观与播放参数调优
窗口尺寸预设：设置里提供 7 档，全部可枚举如下：
| 预设 | 宽度(px) | 高度(px) |
|---|---|---|
| smaller | 828 | 540 |
| small | 920 | 600 |
| medium | 1020 | 660 |
| big（默认） | 1114 | 718 |
| larger | 1202 | 776 |
| oversized | 1385 | 896 |
| huge | 1700 | 1070 |
尺寸定义来自 src/common/config.ts，修改后窗口按所选档位记忆。
主题系统：默认主题为绿意（green），亮/暗模式分别独立记忆（theme.lightId/theme.darkId），支持"道法自然"式的自动亮暗切换，每年 1–2 月还会自动换上新年主题。内置主题图片存放于 src/common/theme/images/，例如中国水墨风与动漫风背景：
播放参数：以下选项均有默认值，集中在 src/common/defaultSetting.ts：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 播放质量 | 128k | 网络好可上调 |
| 播放速度 | 1.0× | 支持变速，默认保持音调（preservesPitch: true） |
| 均衡器 | 10 段全 0 | 频段覆盖 31Hz–16kHz（31/62/125/250/500/1k/2k/4k/8k/16k） |
| 混响（卷积） | 未启用 | 主增益 10、发送增益 0，内置多种预设 |
| 立体声扩展 | 未启用 | 可调节声场与速度 |
| 音调变换 | 1.0 | 改变音调而不改变速度 |
🔗 设备互联与外部控制
数据同步：v2.2.0 起支持三套方案——局域网同步、自建私有服务器、公共服务器。本机默认角色为服务器，监听端口 23332（sync.server.port），其他设备以客户端身份接入，首次配对通过验证码完成，同步内容包括列表、播放数据与设置。相关实现在 src/main/modules/sync/。
开放 API：在"设置 → 开放 API"中启用后，本机启动一个 HTTP 服务，默认端口 23330（openAPI.port），默认只绑定 127.0.0.1，也可勾选绑定局域网供其他设备调用。v2.12.0 起接口新增了音量、静音、播放进度控制与完整歌词获取。接入后可用于定时播放歌单、语音助手接管等自动化场景。
全局快捷键：默认仅窗口内快捷键生效，全局快捷键需手动开启，默认映射如下（可在"设置 → 快捷键"中全部重映射，源码见 src/common/defaultHotKey.ts）：
| 按键 | 动作 |
|---|---|
| Ctrl/⌘ + F5（窗口内） | 播放/暂停 |
| Ctrl/⌘ + ← / →（窗口内） | 上一首 / 下一首 |
| F1（窗口内） | 聚焦搜索框 |
| Ctrl/⌘ + Alt + F5（全局） | 播放/暂停 |
| Ctrl/⌘ + Alt + ↑ / ↓（全局） | 音量加 / 减 |
| Ctrl/⌘ + Alt + 0（全局） | 显示/隐藏桌面歌词 |
另有两个实用开关：启动参数-hidden可让程序直接最小化到托盘；桌面歌词支持置顶、锁定、逐字高亮与翻译/罗马音显示。
🩺 排障与低配设备优化
常见现象与排查方向：
| 现象 | 排查方向 |
|---|---|
| 搜索或播放提示"请求异常" | 换网络（如手机热点）、更换 DNS、检查防火墙或软件内代理设置 |
| Windows 下音频加载失败 | 检查"Internet 选项 → 局域网设置"中是否启用了代理 |
| 同步连接失败 | 确认双方端口 23332 未被防火墙拦截、验证码一致 |
| 下载中断或落盘失败 | 检查磁盘空间、目录写入权限，调低并发（默认 3 个任务） |
低配设备可尝试：关闭透明窗口（common.transparentWindow）、关闭界面动画、减少同时下载数、选用纯色简单主题。
🧭 适合谁，以及下一步
- 在多个平台间频繁切换、不想重复开会员的用户，是它最典型的场景；
- 需要跨设备同步列表与设置的用户，从局域网同步起步最省事；
- 做自动化集成的用户，先启用开放 API 再对接定时任务或语音助手；
- 想贡献代码的用户，从 src/renderer/ 的界面层或 src/renderer/utils/musicSdk/ 的源接口入手。
建议日常备份数据目录，并留意更新日志中的接口变动。
📎 相关文档与源码路径
- 更新日志：CHANGELOG.md
- 常见问题：FAQ.md
- 主界面源码：src/renderer/
- 核心播放器：src/renderer/core/player/
- 音乐源接口：src/renderer/utils/musicSdk/
- 主题构建：src/common/theme/
- 发布脚本：publish/
【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考