企业官网建设流程全解析

小爱音箱音乐播放完整实操：xiaomusic 语音点歌、本地无损、三步部署

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

跟小爱音箱说"播放那首歌"，它翻遍内置曲库也只能回一句"没找到"。想把 NAS 里的无损音乐放出来，或者让家人用一句话点播想听的歌，靠官方功能做不到。xiaomusic 做的就是这件事：接管小爱音箱的音乐播放，本地音乐直接推给音箱，点播的歌曲用 yt-dlp 自动搜索下载后再播放，原有语音交互全部保留。

🐳 最省事的部署方式：Docker 三步跑起来

主推 Docker，全程三条命令。在 NAS 或服务器上依次执行：

mkdir -p /xiaomusic_music /xiaomusic_conf

创建两个空目录：音乐文件目录和配置文件目录，分开放方便日后备份。

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

启动容器，58090 是本机访问端口，8090 是容器内部端口，不要改。国内拉不动镜像的话，把镜像名换成docker.hanxi.cc/hanxi/xiaomusic即可。

然后浏览器打开http://你的IP:58090，在网页上填入小米账号和密码保存，设备列表就会出来，勾选你要用的音箱。带星号的必填项配完就能用，其他选项默认不用动。

其他方式一句话带过：pip 安装适合开发者，pip install -U xiaomusic后执行xiaomusic --config config.json；想直接改源码就用 Dockerfile 和 pdm 本地构建。

🎤 想让家里老人直接语音点播

对音箱说"小爱同学，播放歌曲周杰伦的晴天"，xiaomusic 会自动在线搜索这首歌、下载成 mp3 再播放，老人不需要碰手机。

常用口令都很短："上一首""下一首""停止播放"，播放模式支持"单曲循环""全部循环""随机播放"。还可以说"播放歌单收藏"专门听收藏的歌。口令本身可改：设置页的自定义口令表里，把"播放歌曲"换成"放首歌"也行，改完立即生效。

一个隐藏玩法：说"播放歌曲小猪佩奇的故事"，它会先把内容下载下来再播，给孩子放故事音频很合适。

📁 想把 NAS 里的无损音乐丢进音箱

把音乐目录挂载到容器的/app/music（对应上一步的/xiaomusic_music），本地歌曲就会出现在"播放列表"里，目录名就是歌单名。对音箱说"播放歌单摇滚"，就能只放"摇滚"这个文件夹里的歌，按成员或心情建目录即可。

格式支持 mp3、flac、wav、ape、ogg、m4a。注意 L05B、L05C、LX06、L16A 这几款型号不支持 flac，遇到放不出来的情况，在设置页打开【转换为MP3】和【型号兼容模式】，播放前会先转码，问题就没了。

📻 想给全家建一套网络电台歌单

设置页支持配置 JSON 格式的网络歌单，电台、歌曲都行，也可以直接填别人分享好的歌单内容。手上只有 m3u 电台文件的话，仓库自带 m3u 转换工具，能把 m3u 文件转成项目认识的 json 格式，配好后说"播放歌单"就能循环收听。

⚙️ 最常改的 5 个配置项

配置文件模板在 config-example.json，实际 Docker 部署基本都在网页上配，不需要手写。

已测试支持的设备如下（更多见 README）：

🔍 音箱连不上或没声音，先查这 4 处

设备列表为空或连不上音箱

1. 网页上的小米账号是否保存成功
2. 音箱和服务器是否在同一局域网
3. 重启音箱和容器再试
4. 设置页底部下载日志文件，搜索关键字定位报错

播放有状态但没声音

1. 音箱音量是否为 0
2. 文件格式是否被支持，flac 是否开了转换
3. 换一首本地 mp3 对比测试

在线歌曲下载失败

1. 服务器能否直连外网
2. proxy是否配置了可用代理
3. 需要登录态的源，打开enable_yt_dlp_cookies配置 cookies

口令说了没反应

1. 口令词是否和默认冲突或被改过（查key_word_dict）
2. 音箱是否仍绑定在 xiaomusic 管理的设备列表里

🔧 进阶：插件和主题

内置 Python 插件入口在 plugins/，JS 插件运行器在 js_plugin_runner.js，可以写脚本扩展口令行为（比如"播放歌曲"前跑一段自定义逻辑）。前端也有社区主题可替换，比如仓库静态资源里就带了 pure、tailwind 等多套界面。二次开发入口参考 docs/ 下的文档集合。

写在最后

xiaomusic 的部署门槛很低：Docker 三条命令加一次账号配置，基本就是全部成本，换来的是整屋语音点歌和 NAS 音乐库的自由。需要提醒的是，项目已停止维护，不再接受新功能与 bug 修复，作者建议迁移到社区接力项目 songloft 获取持续支持；如果你只是把现有服务跑稳，照上文步骤装好、把音乐目录挂上就可以开始了，遇到问题优先翻 docs/issues/99.md 这份 FAQ 集合。

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