企业官网建设流程全解析

5 分钟把小爱音箱变成私人曲库：xiaomusic 本地/在线音乐完整上手指南

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

xiaomusic 是一个让小爱音箱音乐播放"不再挑歌源"的开源工具：NAS 或电脑上的音乐目录指过去，小爱音箱直接播本地音乐；想听的在线歌曲则由它用 yt-dlp 现下现播，同时"小爱同学"的语音交互全部保留。

🎯 它适合谁、解决什么问题

小米音箱自带的音乐服务有曲库限制：想听自己下载的歌、想听平台上没有的电台或在线歌曲，就卡住了。xiaomusic 相当于给音箱换了一个可自由配置的音源：

• 听本地收藏：把 NAS 里的音乐目录接给音箱，这就是"小爱音箱播放本地音乐"最直接的姿势
• 听在线歌曲：说个歌名，服务端自动下载并播放，省去手动导入
• 语音照常：原有的"小爱同学"口令不受影响，播放、切歌、循环全靠嘴
• 可扩展：主题、功能都可以通过插件继续加

家里有小米音箱、想搭一个小爱音箱私人音乐库、愿意花几分钟配置的人，基本都能直接用。

🐳 一条命令跑起来：Docker 部署

最省心的路线是 Docker，一条命令就能拿到 Web 控制台，不用折腾 Python 环境：

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

• /xiaomusic_music放音乐、/xiaomusic_conf放配置，可以换成你习惯的目录；报"找不到目录"就先mkdir -p建好
• 启动后浏览器打开http://你的IP:58090进入控制台，后续所有配置都在网页上完成

想要更多掌控力也有备选：Python 环境直接pip install -U xiaomusic后用xiaomusic --config config.json启动（配置可参考 config-example.json）；生产环境图省心就写成 Docker Compose，加个restart: always即可，原理与上面相同。

✅ 部署后马上做的 4 件事

进入 Web 控制台后，按顺序完成这几步：

1. 配小米账号：在设置页填入账号密码并保存，系统会自动拉取你的设备列表
2. 选目标音箱：确认要控制的音箱及其设备号（DID）
3. 放一首歌验证：在播放列表双击任意歌曲快速推送到当前设备，或对着音箱说一句"播放歌曲"
4. 检查安全：如果控制台要暴露到公网，记得开启密码登录并设复杂密码

🗣️ 日常怎么用：说句话就行

常用语音口令，直接对音箱说：

两个小技巧：

• 按文件夹组织曲库：把音乐按主题、心情分目录，之后一句"播放歌单 xx"就能切换场景
• 隐藏玩法：说"播放歌曲小猪佩奇的故事"，它会先搜索下载再播放，给孩子放音频故事很方便

📡 设备、格式与网络：先看这 3 点

兼容型号（常用已测试款，更多见 README）：

音频格式：mp3、flac、wav、ape、ogg、m4a 都支持。注意 L05B、L05C、LX06、L16A 不支持 flac；有文件播不出来时，试试打开"转换为 MP3"和"型号兼容模式"两个开关。

网络前提：音箱和运行 xiaomusic 的机器必须在同一网段（同一个路由器下），语音通道才稳。另外建议不要拿绑定过摄像头等敏感设备的小米账号使用。

🔌 再强一点：插件与网络歌单

• 插件系统：插件目录 里有几个示例插件，自定义口令可以直接触发插件脚本；想加歌词、推荐之类的能力，从这里入手
• 网络歌单：可以配一个 JSON 歌单，电台和歌曲都支持，也能直接用别人分享的链接；控制台附带 m3u 转换工具，电台清单转一下就能用
• 多套主题：仓库里提供 pure、tailwind 等几套界面风格，按喜好切换，用法详见 官方文档

❓ 三个高频问题

连接失败、音箱没反应先确认音箱与服务在同一局域网，再核对设备 DID 是否填对；重启音箱、重新保存一次账号配置。仍不行就从设置页底部下载日志文件找线索。

播放了但没声音先看音箱音量是否被调到最低；格式不兼容时换成 mp3 或开启"转换为 MP3"；换一首其他文件测试，排除单个文件的问题。

在线歌曲下载不下来yt-dlp 依赖外网，试试在设置里配代理或更换搜索前缀；同时确认下载目录可写、磁盘有空间。

🏁 写在最后

xiaomusic 把小爱音箱从"只放固定平台歌单"变成了能播任意音源、还能语音指挥的私人曲库——本地收藏和在线歌曲，一句话的事。

需要说明：项目已停止维护，作者建议迁移到社区接力项目songloft-org/songloft；如果是现在才开始部署，可以直接评估后者，已有环境继续用也不影响。

现在就可以把容器跑起来，5 分钟后，音箱里放的就是你自己挑的歌了。

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