企业官网建设流程全解析

xiaomusic：让小爱音箱突破内置曲库限制的完整部署指南

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

xiaomusic 是一个用 Python 编写的开源工具，它能让你用小爱音箱播放自己选定的音乐：本地曲库随便听，想听的歌还能由 yt-dlp 自动下载后再播。它解决的是一个很具体的卡点——你对着小爱说"播放周杰伦的晴天"，音箱却只在内置平台的有限曲库里打转，还经常循环着听腻的几首。这篇文章按"选型 → 部署 → 场景"的路径走完，全程约 30 分钟，零会员费用。

为什么选 xiaomusic，以及部署前的准备

小爱音箱原生的音乐能力绑定在内置合作曲库上：歌单换不动，格式挑不了，多台设备各听各的。xiaomusic 把播放源换成了你自己的本地目录加 yt-dlp 下载链路，音箱继续当喇叭，选歌权回到你手里。

部署前需要准备：

• 一台常开的设备（NAS、闲置 PC、树莓派 4 均可），Docker 镜像已内置 Python、Node.js 与 ffmpeg；
• 服务器与小爱音箱在同一局域网；
• Docker 与 docker compose（或等效环境），磁盘预留 10GB 以上存放曲库。

💡 部署方式选择指南Docker 方式：镜像自带全部依赖，适合绝大多数用户，本文以它为例； pip 方式（pip install -U xiaomusic）：需要自己准备 Python 环境和 ffmpeg，适合想改源码调试的进阶用户。

# 部署 xiaomusic：建目录、拉代码、启动容器 sudo mkdir -p /xiaomusic_music /xiaomusic_conf git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic docker run -d --name xiaomusic --restart always -p 58090:8090 \ -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic

三步完成部署：容器启动、后台配置与播放验证

容器起来后，剩下的事都在浏览器里完成，按下面三步走。

步骤一：启动容器并确认端口映射

操作目标：让 xiaomusic 以常驻容器运行。关键提示：音乐与配置目录分开映射，58090 是宿主机端口、8090 是容器端口，不要改。常见误区：后台地址写成IP:8090——宿主机应访问映射后的 58090。

1. 执行上一节的 docker 命令，确认容器在运行。
2. 浏览器打开http://服务器IP:58090。
3. 若提示找不到目录，先执行mkdir -p /xiaomusic_music /xiaomusic_conf再重启容器。

• 容器状态为 running，未反复重启
• 后台地址http://服务器IP:58090能正常打开
• 音乐目录已映射为 /app/music

容器能访问，说明网络层没问题，接下来进入 Web 后台做账号与设备绑定。

步骤二：在 Web 页面完成首次配置

操作目标：绑定小米账号并选中要控制的小爱音箱。关键提示：带*号的配置必填，其余保持默认即可。常见误区：只填了账号却忘记保存，设备列表永远是空的。

1. 进入"账号设置"，填入小米账号和密码并保存。
2. 在"小爱设备控制"的设备下拉框里选中目标音箱。
3. 在"设置"中确认 music 目录指向本地曲库路径，然后触发扫描。

• 设备列表中出现你的小爱音箱
• 曲库扫描完成，能列出本地歌曲
• 页面上可切换当前控制设备

账号绑定完成后，链路只差最后一步验证。

步骤三：3 分钟验证播放链路

操作目标：用"界面播一首 + 语音播一首"确认整条链路。关键提示：网络歌曲要先下载再播放，首次需要等几十秒。常见误区：口令没生效就以为是项目问题——先确认设备已在后台选中。

1. 在播放列表里对一首本地歌曲点击快速播放。
2. 对小爱说"播放歌曲周杰伦晴天"，观察它搜索并下载后开播。
3. 再试"下一首"、"随机播放"、"加入收藏"三个基础口令。

• 本地歌曲能出声
• 网络歌曲下载并播放成功
• 三个基础口令全部响应

口令体系全部集中在配置里：中文口令映射到动作，想加专属口令，照着 配置样例 里的 key_word_dict 改几个键值对即可。

场景实战：xiaomusic 在三个真实生活切片里

做饭时，用声音代替手机

我在厨房切菜，腾不出手拿手机，于是直接喊"小爱同学，播放歌曲晴天"——它搜索、下载、播放一气呵成，省去拿手机、解锁、翻曲库的 30 秒。这套"口令 → 搜索 → 下载 → 播放"链路正是 xiaomusic 的核心。

多间房，一个后台管到底

家里客厅、卧室各有一台小爱。用一台服务器跑 xiaomusic，设备下拉框里所有音箱都列在一起，"播放歌单收藏"就能把卧室那台也拉进同一套歌单，多设备不再各听各的。

无损曲库，会员费清零

已购的 FLAC、WAV 文件放进 music 目录即可被扫描收录，无需会员费，折算下来相当于每年省下约 240 元的平台订阅。需要注意：L05B、L05C、LX06、L16A 这几款型号不支持 flac，可在设置里开启【转换为 MP3】和【型号兼容模式】。

🎧 扩展玩法

• 睡前场景：说"10 分钟后关机"，音箱到点自停；
• 专属口令：给"播放歌单收藏"起别名，变成你自己的睡前故事口令；
• 晨间场景：配置 json 格式网络歌单，音箱定时放电台。

避坑清单与下一步行动

• 设备列表为空：账号没绑定或不在同一局域网。1. 检查账号密码是否保存成功；2. 确认音箱与服务器在同一网段。
• 网络歌曲下不动：yt-dlp 源或配置问题。1. 检查 search_prefix 配置；2. 查看设置页底部【下载日志文件】定位报错。
• 老设备播不了 flac：部分型号不支持无损格式。开启【转换为 MP3】与【型号兼容模式】，把曲库统一转成 MP3 即可。

下一步行动：

1. 部署容器：复制上一节命令，把 xiaomusic 跑起来。
2. 建立曲库：挑 50 首左右的本地歌曲完成扫描，跑通一次完整播放。
3. 定义口令：配置三句常用指令，如"播放歌曲+歌名"、"播放歌单+目录名"、"10 分钟后关机"。

项目目前处于维护收尾阶段，遇到问题可先翻仓库 docs 文档 与 issues 合集；如果你愿意提交反馈或插件（参考 plugins 目录 的写法），也欢迎直接参与，社区接力项目会继续承接后续更新。

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