把五个音源装进本地曲库：LX Music 从安装包到开放 API 的完整指南
【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop
LX Music 是一款 Apache 2.0 协议的开源音乐播放器，基于 Electron 与 Vue 3 构建。它把酷我、酷狗、QQ 音乐、网易云、咪咕五个音源收进同一个搜索框，试听音质最高到flac24bit，也支持批量下载并内嵌封面与歌词。本文按"装起来 → 存歌 → 调体验 → 接设备 → 排故障"的路线，带你从零跑通它。
📦 该装哪个安装包？
Windows 分安装版（Setup）和绿色版（green）两类，带x64/x86字样对应系统位数。两者的差别只有一条：只有安装版支持启动时检测新版本并弹窗提示更新，绿色版需要你自己换包。macOS 选.dmg文件；Linux 提供.deb、.rpm、.AppImage、.pacman四种格式，按你的包管理器挑一个。
绿色版从 v1.17.0 起支持便携模式：只要程序文件夹里存在portable文件夹，配置和列表就直接写进这个文件夹，整个目录拷到 U 盘就能带走。
装完启动，主界面四块区域：左侧导航、顶部搜索框、中部歌曲列表、底部播放控制栏。
💾 搜到的歌怎么变成本地曲库？
搜：按F1聚焦顶部搜索框，输入歌名回车。五个音源的结果合并返回，不用先选平台；每条结果旁标着当前可用的档位：128k、320k、flac、flac24bit，具体哪档能用取决于平台和曲目。
听：点任意一条结果直接播放，这首歌会自动加入"我的列表"的试听列表，之后随时能翻到，不用重新搜。想一次放多首，用Ctrl点选或Shift连选后添加到列表即可。
存：批量下载默认关闭，第一次用先去"设置 → 下载"打开开关。选好后右键"下载"，任务进"下载"页面统一管理：能补下失败项，也能把歌加回列表。下载默认保存在桌面，常用默认值如下：
| 设置项 | 默认值 | 什么时候需要改 |
|---|---|---|
| 文件命名 | 歌名 - 歌手 | 想在文件名里带专辑或序号时 |
| 并发任务数 | 3 | 网络稳定想加快批量速度时 |
| 同名文件 | 跳过已存在 | 想覆盖旧文件时才调整 |
| 封面嵌入 | 开启 | 想减小文件体积时关闭 |
| 歌词嵌入 | lxlrc 默认嵌入，普通 lrc 需手动勾选 | 其他播放器要读.lrc内容时 |
| 按列表名分目录 | 关闭 | 想按歌单整理曲库时 |
命名加跳过重复是最省心的组合：同名文件不会互相覆盖，重下也不会产生混乱。
🎨 音质、主题和桌面歌词怎么调？
音质在"设置 → 播放"里选。默认128k，日常够听还省流量，网络条件好再调高。"出错自动跳过"默认开启，某首歌加载失败时直接切下一首，不用手动处理。
主题默认是绿色，内置主题一键切换，其中水墨、月夜两套比较出挑；设置里也能自建主题，拖一张背景图配上主色即可。
桌面歌词默认关闭，在"设置 → 桌面歌词"开启后它是一个独立小窗，默认尺寸450×300。可调项：横排或竖排、字号、已播与未播歌词颜色、窗口透明度；窗口支持锁定位置和始终置顶。主窗口全屏或歌曲暂停时它默认自动隐藏，不挡屏幕。
快捷键分应用内和全局两套，在"设置 → 快捷键"管理。应用内默认启用，全局默认关闭：
| 按键 | 作用 | 生效范围 |
|---|---|---|
Ctrl+F5 | 播放 / 暂停 | 应用内 |
Ctrl+←/Ctrl+→ | 上一曲 / 下一曲 | 应用内 |
Ctrl+Alt+F5 | 播放 / 暂停 | 全局 |
Ctrl+Alt+←/→ | 上一曲 / 下一曲 | 全局 |
Ctrl+Alt+↑/↓ | 音量加 / 减 | 全局 |
Ctrl+Alt+0 | 桌面歌词显隐 | 全局 |
macOS 上Ctrl对应Cmd。建议至少打开全局的播放/暂停和桌面歌词显隐两项，切窗口后还能顺手控制。
🔌 开放 API、数据同步和自定义音源什么时候开？
这三项都在设置里，默认全部未启用，用哪个开哪个。
数据同步：在"设置 → 数据同步"开启后，PC 端启动本地服务，默认端口23332；手机端填上 PC 的局域网地址，歌单、列表、设置就能在多台设备间互相同步。传输是明文，只在可信局域网里用；首次同步前先把列表备份一次，出问题还能回滚。
开放 API：在"设置 → 开放 API"开启后，本机起一个 HTTP 服务，默认只监听127.0.0.1:23330，即只接受本机调用。对外暴露/status、/play、/pause、/skip-next、/lyric、/volume、/seek、/collect等端点；其中/subscribe-player-status以 SSE 事件流持续推送播放状态，做歌词桌宠、状态面板这类小工具最方便。服务起来没有，一条命令验证：
curl http://127.0.0.1:23330/status返回当前播放状态的 JSON 说明端点可用。实现可以看 src/main/modules/openApi/。
自定义音源：在"设置 → 音乐来源"导入一个 JavaScript 脚本。脚本声明它支持的源和musicUrl动作，被调用时返回该歌曲的直链；脚本里可以直接用lx.request发请求，不受跨域限制且跟随软件内的代理设置，加解密自带 AES、MD5、RSA 工具函数，够应付大多数音源的签名逻辑。运行时实现在 src/main/modules/userApi/。适合给某个平台加专属音源，或在默认音源不稳定时留一条备用链路。
🛠 搜索不工作或界面空白怎么排查？
现象：搜索整页刷不出来，所有歌曲提示请求异常。原因：当前接口源不可用，或本机 DNS 到不了接口服务器。解法：先去"设置 → 音乐来源"换一个接口源；再连手机热点验证是不是网络问题；都不行就把 DNS 改成223.6.6.6或8.8.8.8，改完重启软件。按这个顺序排，别跳步。
现象：Windows 10/11 上界面整屏空白，或窗口显示不全。原因：GPU 沙箱与显卡驱动冲突，属于渲染层问题。解法：给快捷方式加启动参数--disable-gpu-sandbox；没效果再逐个换成--no-sandbox、-dha、--disable-gpu，恢复显示的那个就是你要的参数。
现象：下载任务报错ENOENT: no such file or directory, mkdir。原因：所选下载目录没有读写权限，软件连建文件夹都做不到。解法：把下载目录换成有权限的路径，比如用户主目录下自己新建的文件夹。
数据目录速查与落地建议
配置、列表、下载缓存都存在平台固定的数据目录里：
- Windows：
%APPDATA%/lx-music-desktop - Linux：
~/.config/lx-music-desktop - macOS：
~/Library/Application Support/lx-music-desktop - 例外：绿色版（v1.17.0 及以上）程序目录下有
portable文件夹时，数据直接写进该文件夹
给你的三条建议：
- 新手直接装 Windows 安装版（Setup），因为更新提示是现成的，绿色版每次都要自己换包；
- 日常遇到问题按"换源 → 换网 → 改 DNS"的顺序排一遍，别跳步，日常故障基本都卡在接口源上；
- 想往深挖，先开一个开放 API 玩起来，自定义音源和桌面歌词都建立在这套本地服务之上，先跑通
/status再扩展。
【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
