LX Music 开源音乐播放器完整指南：五音源搜索、批量下载与本地曲库

【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop

lx-music-desktop 是一款 Apache 2.0 协议的开源音乐播放器，基于 Electron + Vue 3 构建。它把酷我、酷狗、QQ音乐、网易云、咪咕五个音源的搜索收进同一个搜索框，试听最高到 flac24bit，也能批量下载歌曲存成本地曲库。适合想把多个平台的歌集中到一个离线库的人。

🚀 30 秒上手：选对安装包并搜到第一首歌

1. 选安装包：Windows 用安装版（Setup）或绿色版，x64/x86按系统位数选；macOS 用.dmg；Linux 从.deb/.rpm/.AppImage/.pacman里按发行版挑一个。
2. 安装版启动时会自动检查并提示更新，绿色版没有这项能力；绿色版从 v1.17.0 起，程序目录里放一个portable文件夹，配置和列表就会写进该文件夹，整个目录拷到 U 盘即可带走。
3. macOS 首次启动若提示"已损坏"，先在终端运行下面这条命令，解除系统对未签名应用的拦截：

sudo xattr -rd com.apple.quarantine /Applications/lx-music-desktop.app

4. 启动后界面分四块：左侧导航、顶部搜索框、中部歌曲列表、底部播放栏。
5. 按F1聚焦搜索框，输入歌名回车，五个音源的结果合并展示，每条结果旁标注可用音质；点击任意一条直接播放，这首歌会自动进入"我的列表"。

🧩 场景任务卡：四个常见需求

把歌存成本地曲库：批量下载

入口：设置 → 下载。下载开关默认是关闭的，先打开它才算第一步。

步骤：

1. 打开"启用下载"开关。
2. 在歌曲列表里按住 Ctrl 点选单首、Shift 连选，或按Ctrl+A全选。
3. 右键选中项选择"下载"，任务自动排队执行。
4. 到"下载"页面统一管理：可直接播放、重试失败任务、右键把歌加回列表。

坑：下载目录设在无权限的路径上时，任务会报ENOENT、mkdir错误，换成自己新建的目录即可。默认"跳过已存在"下重复下载不会覆盖旧文件，想覆盖才需要改这项。

一句话价值：歌存在本机，封面和 lxlrc 歌词自动写进音频文件，其他播放器也能直接读取。

打磨界面：主题与桌面歌词

入口：设置 → 桌面歌词 与 设置 → 主题，两个入口分别管歌词窗和界面配色。

步骤：

1. 在"设置 → 桌面歌词"打开歌词开关，会弹出一个独立小窗，默认 450×300，横排。
2. 同页可调字号、已播与未播歌词颜色、窗口透明度，位置锁定和始终置顶按需勾选。
3. 在"设置 → 主题"里一键切换内置主题，水墨和月夜两套对比明显。
4. 自建主题：拖一张背景图、定一个主色，保存后应用。

坑：主窗口全屏或歌曲暂停时，歌词窗默认自动隐藏，找不到它时先关掉这两项。歌词窗是独立窗口，关闭主窗口不影响它继续显示。

一句话价值：歌词常驻屏幕角落而不占主窗口，界面配色也能整体换风格。

连接多台设备：数据同步与开放 API

入口：设置 → 数据同步 与 设置 → 开放 API，两者默认都未启用，用到哪个开哪个。

步骤：

1. "设置 → 数据同步"里启动本地服务，默认监听端口 23332。
2. 手机端填入 PC 的局域网地址和端口，歌单、列表、设置即可两端互相同步。
3. "设置 → 开放 API"里开启 HTTP 服务，默认只监听127.0.0.1:23330，仅本机可调。
4. 服务暴露/status、/play、/pause、/seek、/volume等端点，/subscribe-player-status以 SSE 事件流持续推送播放状态，实现代码见 开放 API 模块。

坑：同步传输是明文，只在可信局域网里用，首次同步前先备份一次列表留退路。开放 API 想被局域网内其他设备调用，需先开启"监听局域网"选项。

服务是否起来，本机跑一条命令即可验证，返回当前播放状态的 JSON 说明端点可用：

curl http://127.0.0.1:23330/status

一句话价值：手机与电脑共用一份曲库，桌面歌词宠、状态面板这类小工具也能挂在这套本地服务上。

扩展能力边界：自定义音源

入口：把 JavaScript 脚本放进用户数据目录，在设置里导入。

步骤：

1. 用 UTF-8 编码写脚本，在inited事件里声明支持的源和musicUrl动作。
2. 监听request事件，按传入音质返回该歌曲的 http/https 直链。
3. 脚本内直接用lx.request发请求，不受浏览器跨域限制，并跟随软件里的代理设置。
4. 接口签名用自带的 AES、MD5、RSA 等工具函数处理，运行时实现见 自定义音源模块。

坑：事件回调必须返回 Promise；忘记发送inited事件，应用会认为该源初始化失败。

一句话价值：给不稳定的默认音源留一条备用链路。

📋 默认值速查：LX Music 关键参数表

注：表中 Ctrl 在 macOS 上对应 Cmd 键。

🔍 故障自查路线：LX Music 高频问题排查

搜索页刷不出内容、歌曲提示请求异常

现象：搜索整页无结果，点歌播放提示请求异常。

排查顺序：

1. 在"设置 → 音乐来源"切换到另一个接口源，重新搜索。
2. 连手机热点复测，确认是否本机网络的问题。
3. 把 DNS 改成 223.6.6.6 或 8.8.8.8，改完重启软件再试。

常见根因：当前接口源不可用，或本机网络与 DNS 根本到不了接口服务器。

Windows 10 / 11 界面整屏空白

现象：启动后整屏空白，或窗口只渲染出一部分。

排查顺序：

1. 给快捷方式追加启动参数--disable-gpu-sandbox后启动。
2. 无效就依次换成--no-sandbox、-dha、--disable-gpu逐个尝试。
3. 任务管理器里有进程却无图标时，更换软件安装目录重装。

常见根因：GPU 沙箱与显卡驱动冲突，属于渲染层问题，数据没有丢失。

下载任务报 ENOENT

现象：任务报错ENOENT: no such file or directory, mkdir。

排查顺序：

1. 打开"设置 → 下载"，检查下载目录指向哪里。
2. 换成用户主目录下自己新建的目录，重新下载。

常见根因：下载目录没有读写权限，软件连建文件夹都做不到。

收尾：数据文件在哪，先做什么

配置、列表、下载缓存都存在平台固定的数据目录：Windows 是%APPDATA%/lx-music-desktop，Linux 是~/.config/lx-music-desktop，macOS 是~/Library/Application Support/lx-music-desktop；绿色版（v1.17.0 及以上）程序目录里存在portable文件夹时，数据改写到该文件夹。推荐顺序：先搜索试听，再打开下载开关把常听的歌存下来，最后按需启用同步或开放 API。

【免费下载链接】lx-music-desktop一个基于 Electron 的音乐软件项目地址: https://gitcode.com/GitHub_Trending/lx/lx-music-desktop