快速上手小爱音箱音乐播放：xiaomusic 的部署与日常使用指南-开发者社区

快速上手小爱音箱音乐播放：xiaomusic 的部署与日常使用指南

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic

xiaomusic（小爱音箱音乐播放）是一个开源工具：把电脑或 NAS 上的本地音乐推到小爱音箱播放，也能用 yt-dlp 下载网络歌曲，同时保留"小爱同学"的语音交互。它主要服务于想在自家小爱音箱上脱离内置曲库的用户。本文按"最快部署方式、其余方式怎么选、实际怎么用、兼容速查"的顺序，把部署和日常操作一次讲清。

📌 项目速览

一句话定位：xiaomusic 是小爱音箱的第三方音乐播放服务，本地曲库与网络资源都能播，语音口令照常工作。

核心能力如下：

播放本地音乐文件，音乐库放在 NAS 或任意 Linux 目录即可
用 yt-dlp 下载在线歌曲或电台，边下边播
保留小爱音箱原生语音交互，口令可自定义
提供 Web 控制台，管理播放列表、歌单与设备
支持 JSON 格式网络歌单，附 M3U 转换工具
插件机制可扩展主题与新功能，源码见 plugins/

它绕开的是音箱内置音乐服务的曲库限制；音量、语音唤醒等原生能力不受影响。

🐳 最快上手：3 步用 Docker 跑起来

最省事的路径是 Docker 部署，不需要准备 Python 环境，3 步完成。

复制配置模板：cp config-example.json config.json。
编辑config.json，填入小米账号信息与音箱设备 DID，端口保持默认 8090 即可。
启动容器：

docker run -p 58090:8090 \ -v /xiaomusic_music:/app/music \ -v /xiaomusic_conf:/app/conf \ hanxi/xiaomusic

浏览器打开http://你的IP:58090就能进入控制台。注意 58090 是你本机的映射端口，8090 是容器内端口，不建议改动。

🧭 其他部署方式怎么选

另一条路径是 Python 环境，适合想改源码、写插件的人；长期跑在服务器上的生产环境则推荐 Docker Compose。三种方式对照如下：

方式	适合人群	一句话说明
Docker 一行命令	新手、NAS 用户	免依赖，群晖、威联通等主流 NAS 都能跑
Docker Compose	生产环境	自动重启、数据持久化、便于升级与多服务编排
pip 安装 Python 版	开发者	`pip install -U xiaomusic`后执行`xiaomusic --config config.json`，便于调试与二次开发

更详细的文档与历史问题记录可查 docs/issues/ 目录。

🎧 按场景使用

下面按三个常见场景说明日常怎么用，覆盖本地播放、在线下载和纯语音操作。

场景一：播放本地音乐。把音乐文件放进挂载的/app/music目录后，控制台会自动扫描出全部歌曲，按"所有歌曲 / 收藏 / 下载"分类浏览，支持搜索、双击即播、删除与收藏。

场景二：下载并播放在线歌曲。对小爱说"播放歌曲某某"，服务会调用 yt-dlp 在线下载再播放；给家里孩子放故事音频也走同样的路径，首次等待稍长，之后走本地缓存。

场景三：纯语音控制，不动控制台。常用口令包括"播放歌曲""上一首/下一首""停止播放""单曲循环/全部循环/随机播放""播放歌单收藏""加入收藏/取消收藏"。此外，网络歌单用 JSON 配置即可自定义主题分类，M3U 电台文件可以转换后直接接入。

📷 设备与格式兼容速查

设备兼容情况以官方已验证列表为准，更多型号可查看 docs/issues/ 中的讨论记录：

设备型号	设备名称	支持状态
L06A	小爱音箱	完全支持
L07A	Redmi小爱音箱 Play	完全支持
LX06	小爱音箱Pro	完全支持
L16A	Xiaomi Sound	完全支持
LX01	小爱音箱mini	完全支持