手把手教你用 LX Music + XiaoMusic，让小爱音箱播放你的本地音乐库

为什么需要这套方案？

“小爱同学，播放《加州旅馆》。”
“抱歉，由于版权限制，暂时无法播放。”

这句冷冰冰的提示，相信很多智能音箱用户都听过。明明电脑硬盘里存着从正版CD抓轨的无损音乐，NAS里躺着十年的收藏，可小爱音箱只认自己绑定的那几家流媒体曲库。想随心所欲听自己的歌，仿佛要翻一座墙。

其实突破这堵墙的技术路线很清晰：LX Music 负责管理本地音乐并提供播放控制接口，XiaoMusic 充当小爱音箱的“翻译官”，把语音指令转译成对本地曲库的检索、下载和播放命令。下面我会详细拆解这对组合怎么装、怎么配，以及真正让你家小爱音箱“什么都能播”。

一、核心组件各司其职

LX Music：本地音乐总控台

LX Music（洛雪音乐）是一款开源、纯粹的桌面音乐播放器，支持 Windows、macOS 和 Linux。它不提供音乐内容，而是通过加载外部 JavaScript 音源插件，从公开的 API 接口聚合搜索与试听数据。
从 v2.10.0 开始，LX Music 开放了本地 API 服务（默认端口 10762），允许外部程序控制播放、切歌、收藏等操作。这个能力是后续与小爱音箱联动的关键——XiaoMusic 可以通过调用 LX Music 的 API，实现对本地曲库的精细化管理。https://wxa.wxs.qq.com/tmpl/ps/base_tmpl.html

XiaoMusic：小爱音箱的外挂大脑

XiaoMusic 是 GitHub 上的开源 Python 项目（作者 hanxi），专为解决“小爱音箱曲库受限”而设计。它的工作流程分三步：

1. 接收语音指令：通过小米 MiNA/MiIO 协议与音箱通信，捕获用户的播放请求。
2. 本地优先检索：先在你挂载的音乐文件夹中搜索匹配的歌曲。
3. 网络自动补全：如果本地没有，调用 yt-dlp 从 B 站、YouTube 等平台下载音频，再推送给音箱播放。

目前已适配 20 多种小爱音箱型号（小爱音箱 Pro、Xiaomi Sound、Redmi 小爱 Play、触屏版等），支持 Docker 一键部署，可跑在 NAS、树莓派、常年开机的电脑上。

二、手把手部署（从零到播放）

准备工作

• 一台能 7×24 小时运行的设备（NAS / 树莓派 / 旧电脑）。如果没有，也可以用常开的 PC 跑 Python 版。
• 小爱音箱与设备处于同一局域网。
• 音乐文件集中存放在一个文件夹中（比如 /data/music）。

第 1 步：用 Docker 部署 XiaoMusic（推荐）

创建 docker-compose.yaml：

yaml

• services: 
• xiaomusic:   
• image: hanxi/xiaomusic   
• container_name: xiaomusic   
• restart: unless-stopped   
• ports:     
• - 58090:8090   
• environment:     
• XIAOMUSIC_PUBLIC_PORT: 58090   
• volumes:     
• - /你的音乐文件夹路径:/app/music     
• - ./xiaomusic_conf:/app/conf

国内用户若拉取镜像较慢，可将 image 替换为 docker.hanxi.cc/hanxi/xiaomusic。
在 docker-compose.yml 目录下执行 docker compose up -d，然后访问 http://你的设备IP:58090，即可看到 XiaoMusic 的 Web 界面。

第 2 步：配置 XiaoMusic

1. 登录小米账号：在 Web 界面的“设置”中填写小米账号和密码（需与米家 App 中登录的账号一致）。XiaoMusic 借此获得控制音箱的权限。
2. 绑定音箱：在“设备列表”中勾选你要使用的那台小爱音箱，点击保存。如果列表为空，去米家 App 退出账号再重新登录，刷新页面即可。
3. 挂载音乐目录：上面 volumes 中已经将本地文件夹映射到容器内的 /app/music，XiaoMusic 会自动扫描并生成播放列表。

第 3 步：（可选）与 LX Music 联动

如果你习惯用 LX Music 管理歌单、控制播放，可以在 LX Music 的“设置 → 开放 API 服务”中启用 API（默认端口 10762），然后在 XiaoMusic 的设置里填入 LX Music 所在设备的 IP 和端口。这样 XiaoMusic 可以通过 API 告诉 LX Music 该播放哪首歌，实现更丰富的播放控制。

如果你没有常开的 LX Music 桌面端，也可以完全依赖 XiaoMusic 的本地文件扫描和网络下载功能，单它一个就足够了。

第 4 步：让小爱听懂你的指令

一切配置就绪后，对小爱音箱说出以下指令（注意是中文自然语言）：

注意：首次播放某首网络歌曲时，XiaoMusic 需要下载（几秒到几十秒），之后再播就是本地文件了。

三、避坑指南（常见问题与解决）

1. 镜像拉取失败

换用国内镜像 docker.hanxi.cc/hanxi/xiaomusic。如果仍需代理，可以在 Docker 环境中添加 HTTP_PROXY 环境变量。

2. 登录小米账号后找不到音箱设备

• 确认音箱与运行 XiaoMusic 的设备在同一局域网。
• 去米家 App 退出账号重新登录，再回 XiaoMusic 页面刷新设备列表。

3. 部分型号小爱音箱无法播放 FLAC

在 XiaoMusic 设置中开启“转换为 MP3”，系统会自动转码再推送。

4. 小米账号 Token 过期

每隔一段时间需要重新登录。在 XiaoMusic Web 界面重新输入账号密码保存即可。

5. 下载歌曲只得到一小段或失败

说明 yt-dlp 的默认搜索源（ytsearch）可能失效。在设置中将搜索源改为 bilisearch（B 站），B 站的音频资源通常更稳定。

6. 想用 LX Music 但音源插件频频失效

LX Music 本身不提供任何音源，JS 插件由社区维护。多准备几个备用音源链接，或在“在线导入”中寻找更新频繁的来源。更推荐的做法：把真正常听的歌通过 XiaoMusic 下载到本地，以后都是本地播放，不再依赖在线音源。

四、这套方案能带给你什么？

部署完成后，你会拥有一个真正“自由”的音乐播放体系：

• 版权彻底无感：音箱能播你的全部本地音乐，遇到没有的歌曲自动从公开视频网站下载一次，之后就是本地文件。
• 语音控制自然：不需要切换 App 或投屏，直接对小爱说就行。
• 多音箱、多设备：XiaoMusic 可以同时管理你家里多台小爱音箱，互不干扰。
• 低成本、低功耗：一台树莓派或 NAS 就能跑 Docker 版，全年耗电几乎可忽略。

五、总结：把播放权拿回自己手里

LX Music 和 XiaoMusic 的组合，本质上是把两个原本孤立的能力拼接在了一起：前者的播放管理与本地曲库能力，后者的小爱音箱控制与自动化补全能力。开源社区用技术手段回答了那个经典问题：我买的音箱，凭什么不能放我自己的歌？

这套方案并不需要你拥有计算机专业背景——跟着上面的 Docker 步骤，10 分钟就能跑起来。如果你恰好有一台 NAS 或者不关机的电脑，更是“即装即用”。从今往后，你只需要对小爱同学说一句“播放一首老歌”，剩下的，交给代码。

本文转自：https://mp.weixin.qq.com/s/tbpAjvs-XS77ZHKnSg7xWw