企业官网建设流程全解析

XiaoMusic 完全指南：用 Docker 为小爱音箱部署免费音乐播放方案

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

XiaoMusic 是面向小爱音箱的开源音乐播放工具：它接管音箱的语音指令，用 yt-dlp 把在线音乐下载到本地音乐库，再由音箱播放。本文覆盖 Docker 部署、日常语音指令和自定义口令配置，5 分钟即可完成上线。

适用场景：哪些人适合部署

XiaoMusic 对应几类常见情况：

• 不少歌曲不开通音乐会员就无法播放；
• 内置曲库有限，歌曲时有缺漏；
• 想把个人收藏的音乐放到音箱上，但没有入口；
• 不同房间的不同音箱想播不同内容。

满足以上任意一条，并且手边有一台能长期运行 Docker 的机器（或 NAS），就可以部署。

工作原理：语音指令如何变成本地文件

XiaoMusic 的链路是"语音拦截 → 在线下载 → 本地播放"三步：

1. 接管指令：通过小米账号连接音箱，拦截歌曲类播放指令；
2. 搜索下载：本地音乐库中没有的歌，会调用 yt-dlp 引擎从音乐平台搜索并下载，yt-dlp 支持全球主流平台，海外曲库资源也能覆盖；
3. 本地播放：下载的文件进入本地音乐目录，之后的播放直接读本地，网页端可以浏览、搜索和管理曲库。

因此大多数歌曲只在第一次点播时联网下载，后续都是本地读取，等待时间基本可以忽略。

🐳 5 分钟上手：Docker 一条命令部署

容器起来后，浏览器访问http://服务器IP:58090即可进入 Web 管理页。

Docker 启动

在已装 Docker 的服务器上执行：

docker run -p 58090:8090 \ -v /home/你的用户名/music:/app/music \ -v /home/你的用户名/conf:/app/conf \ hanxi/xiaomusic

几点说明：

• 58090:8090是宿主机端口映射到容器的 8090，宿主端口可自定，容器端口保持不变；
• music 与 conf 两个目录建议分开：music 存下载的音乐，conf 存配置文件。

首次配置

首次打开页面，只需填必填项（带*标记）：

1. 输入小米账号与密码并保存，之后才能拉到设备列表；
2. 确认音乐存储路径与服务端口（默认 8090）；
3. 其余选项用不到就保持默认。

配置项对应 conf 目录里的配置文件，仓库中提供了完整示例：config-example.json。

源码方式启动

不使用 Docker 也可以从源码运行：

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic cd xiaomusic pip install -r requirements.txt python xiaomusic.py

日常使用：语音指令速查表

部署完成后全部靠语音控制，无需碰页面。家里有多台音箱时，可在网页右上角切换当前设备。

播放与模式控制

歌单与收藏

一个附赠玩法

"播放歌曲+歌名"这个指令对非音乐内容同样生效：说"播放歌曲小猪佩奇的故事"，它会先下载对应音频再播放，有小孩的家庭可以直接当故事机用。

自定义语音指令字典配置

XiaoMusic 的口令全部由指令字典驱动：内置指令集是key_word_dict，用户可自行在user_key_word_dict中添加口令，指令体支持exec#code1(...)调用自定义脚本：

"user_key_word_dict": { "晨间唤醒": "exec#code1(\"播放晨间音乐\")", "晚餐时光": "exec#code1(\"播放轻音乐\")", "睡前安眠": "exec#code1(\"播放白噪音\")" }

示例脚本位于 plugins/ 目录，可参考code1.py的结构编写自己的逻辑。

配置文件关键项

常用配置项如下，可在网页上填写，也可直接改配置文件：

网络歌单与 M3U 电台转换

本地库之外，XiaoMusic 还支持网络歌单：

• 歌单为 JSON 格式，支持电台和歌曲两类；
• 别人做好的歌单，可以直接使用其分享链接；
• 手上有 M3U 电台文件的话，可用网页内的转换工具把它转成 JSON 网络歌单。

设备兼容与音频格式核对

已测试支持的型号

以下型号经过官方测试支持：

设备不在列表里也可以直接尝试，多数小爱音箱都能正常播放，完整兼容列表见仓库 README.md。

支持的音频格式

本地库可识别 mp3、flac、wav、ape、ogg、m4a，下载的歌曲为 mp3。部分型号（如 L05B、L05C、LX06、L16A）不支持 flac，遇到格式播不了时，可在设置中打开"转换为MP3"与"型号兼容模式"。

部署前避坑清单

常见问题排查

• 连不上音箱：先核对小米账号密码是否正确，再检查网络；仍不行就从网页下载日志文件排查原因；
• 音质：下载的歌为 mp3，想要更高音质可直接把 flac、wav 等文件放进本地音乐目录；
• 查资料：遇到问题先翻官方文档：docs/index.md。

另需说明：项目 README 中已标注停止维护，作者推荐社区接力项目 songloft，打算长期部署的话请留意这一状态。

安全与账号保护

• 需要公网访问网页时，务必开启密码登录并设置复杂密码；
• 不要在公共场所的 WiFi 环境下使用，避免小米账号密码泄露；
• 不建议把绑定小米账号的账号同时用于摄像头等设备，一旦凭据泄露，影响面会扩大。

手边有家用服务器和小爱音箱的话，可以照着上面的 Docker 命令跑一遍，让音箱播起第一首本地下载的歌。

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