企业官网建设流程全解析

从零开始轻松部署 XiaoMusic，让小爱音箱彻底告别会员限制随心播放私人音乐库

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

你是否也遇到过这样的场景：明明自己电脑里存着几百首高音质音乐，却只能打开手机 App 一首首手动切换；家里的小爱音箱每天都在，却只会回答"抱歉，没有找到相关歌曲"。有没有想过，只需对小爱说一句"播放周杰伦的晴天"，音箱就能立刻响起你收藏的旋律？今天要介绍的 XiaoMusic 正是为此而生——一个让小爱音箱变身私人音乐管家的开源项目，用 yt-dlp 下载音乐，让本地与在线资源都能通过语音随心播放。

先看成果：十分钟跑通第一个最小可用 Demo

先别急着研究原理，我们直接把最激动人心的部分提前——用最简单的两条命令，让 XiaoMusic 跑起来，然后亲耳听到小爱音箱为你播放第一首歌。

第一步：准备两个目录

在你的电脑或 NAS 上，先规划好两个文件夹：

mkdir -p /xiaomusic_music mkdir -p /xiaomusic_conf

这段命令创建了两个目录：music目录用来存放你的音乐文件，conf目录用来保存 XiaoMusic 的配置和账号信息。两个目录分开存放，以后备份、迁移都会非常省心。

第二步：用 Docker Compose 一键拉起服务

创建一个docker-compose.yml文件，内容如下：

services: xiaomusic: image: docker.hanxi.cc/hanxi/xiaomusic container_name: xiaomusic restart: always ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf

这段配置做了三件事：从国内镜像源拉取 XiaoMusic 镜像；把宿主机的 58090 端口映射到容器内的 8090 端口；把前面创建的两个目录挂载进容器。如果你身处海外，把image换成hanxi/xiaomusic即可，其余不变。

第三步：启动并打开管理界面

docker compose up -d

等待镜像下载完成后，在浏览器访问http://你的设备IP:58090，你就能看到 XiaoMusic 的 Web 管理界面。第一次打开时，需要完成一次"绑定"：在设置页输入小米账号和密码保存，系统会自动获取你的设备列表，勾选你要控制的小爱音箱，再次保存即可。

XiaoMusic 的 Web 界面自带功能标注，几乎每个按钮都告诉你该点哪里

到这里，最小可用 Demo 就已经跑通了。现在试着在网页里搜索一首歌点击播放，如果音箱响起音乐，恭喜你，最难的 20% 已经完成！

复盘原理：它到底是怎么听懂小爱说话的

体验过后，我们来拆解一下这个神奇的桥梁是如何工作的。你可以把 XiaoMusic 想象成一位"同声传译官"——它坐在你的小爱音箱和音乐库中间，一边监听小爱说了什么，一边把指令翻译成音乐播放动作。

整个工作流大致是这样的：

1. 监听对话：XiaoMusic 会周期性地拉取小爱的对话记录，识别出你设定的口令关键词（默认是"播放歌曲"）。
2. 解析指令：把"播放歌曲周杰伦晴天"拆解成歌手"周杰伦"和歌名"晴天"，支持模糊匹配，说错一两个字也能找到。
3. 寻找音乐：先在本地音乐库搜索，找不到就用 yt-dlp 从网络下载到本地目录。
4. 推送播放：通过小米的服务接口，把音乐链接推送给音箱开始播放，同时接管播放、暂停、切歌等控制权。

在 Web 界面里，你的每一首本地歌曲都清晰可查、双击即播

看到这里你会发现，XiaoMusic 本质上是一个"语音指令翻译器 + 音乐下载器 + 音箱控制器"的三合一工具，核心代码都在xiaomusic/目录下，想深入研究的同学可以翻阅xiaomusic/xiaomusic.py和xiaomusic/command_handler.py这两个文件。

深入配置：把每个关键开关都调到最顺手

Demo 跑通只是开始，接下来我们逐个梳理那些值得关注的配置项，让 XiaoMusic 更贴合你的使用习惯。

1. 语音口令：让小爱听懂你的话

默认口令是"播放歌曲"，你可以完全自定义。打开xiaomusic/plugins-config-example.json或直接在设置页里配置关键词：

{ "keywords_play": "播放歌曲,放歌曲", "keywords_playlist": "播放列表,播放歌单", "keywords_stop": "关机,暂停,停止,停止播放" }

这段配置定义了四类指令的触发词：播放、播放歌单、停止播放。你可以把"放歌曲"改成"来一首"，让指令更符合你的说话习惯。

2. 播放模式与收藏

XiaoMusic 支持完整的播放模式控制，用语音就能切换：

🎯隐藏玩法：对小爱说"播放歌曲小猪佩奇的故事"，XiaoMusic 会先自动搜索下载相关内容，再开始播放。家里有孩子的朋友，这一条值得立刻试试。

3. 音质与兼容性

XiaoMusic 支持 MP3、FLAC、WAV、APE、OGG、M4A 等常见格式。如果你的音箱型号较旧（如 L05B、L05C），建议在设置里打开转换为 MP3选项，虽然会消耗一些 CPU，但能保证老设备稳定播放。

进阶玩法：把 XiaoMusic 玩出花来

当你熟悉了基本操作，是时候探索这些隐藏能力了。

定时任务：让音乐自动唤醒你

XiaoMusic 内置了 crontab 格式的定时任务，在设置页面的"定时任务"配置里填入 JSON 即可。比如每天早晨 7 点播放周杰伦的晴天：

[ { "expression": "0 7 * * *", "name": "play", "did": "123456789", "arg1": "周杰伦晴天" } ]

这里expression是标准的 cron 表达式（0 7 * * * 表示每天 7 点），name是任务类型，arg1是播放内容。更实用的场景是：每天晚上 12 点自动关闭对话记录拉取、早上 6 点重新开启，能有效缓解小米接口的风控限制。完整任务类型见文档docs/issues/182.md。

网络歌单：把电台搬进音箱

除了本地音乐，XiaoMusic 还支持 JSON 格式的网络歌单，可以配置电台或 m3u8 直播流。在设置页填入歌单 URL，就能让小爱播放网络电台。格式示例见docs/issues/78.md，还贴心地配备了 m3u 转 json 的转换工具。

自定义口令：写一行插件扩展能力

XiaoMusic 的口令支持exec前缀调用插件，项目自带的plugins/目录里就有现成例子。例如plugins/code1.py演示了如何自定义一条语音回复，plugins/httpget.py演示了如何让口令触发一次网络请求。如果你想写自己的插件，参考这两个文件就能快速上手。

多设备与多目录

家里有多台小爱音箱？在 Web 界面切换设备即可让音乐在不同房间流转。音乐目录也支持多个，用 Docker 挂载多个子目录即可，每一层文件夹会自动识别为一个播放列表。

避坑手册：高频故障自查清单

根据社区反馈，我把最常遇到的问题整理成了"问题→原因→解决"的对照表，遇到状况直接按图索骥。

问题 1：登录失败，后台看不到设备列表

• 原因：小米账号在官网登录过滑块验证后，旧会话失效；或本地开了加速代理。
• 解决：先去官网www.mi.com完成一次登录验证；关掉本地代理；用局域网内的手机重新登录米家 App；必要时改用 cookie 登录。

问题 2：网页能播放，语音却无响应

• 原因：语音口令功能默认是关闭的，需要手动开启"获取对话记录"开关。
• 解决：到设置页打开对应开关，保存后重启容器。注意这个功能会频繁请求接口，不用时随手关闭，防止触发风控。

问题 3：日志显示在播放，音箱却没有声音

• 原因：多半是hostname配错了地址，音箱访问不到你的服务。
• 解决：检查设置里的地址是否为 NAS 的局域网 IP，且与音箱在同一网段；用浏览器打开日志里的歌曲链接测试能否访问；确认端口映射是否被修改过。

问题 4：flac 格式无法播放

• 原因：部分型号（如 L05B、L05C、LX06、L16A）不支持 flac 格式。
• 解决：开启"转换为 MP3"选项，或提前用工具批量转码。

问题 5：容器日志提示 DNS 解析错误

• 原因：容器无法解析小米域名。
• 解决：把主机的 DNS 改为223.5.5.5后重启 Docker，或者把容器网络模式改为 host 模式。

💡通用排查技巧：遇到任何疑难杂症，先去 Web 设置页底部点击"下载日志文件"，用日志定位问题再求助，比盲猜高效得多。

安全与运维：安心使用的几个底线

XiaoMusic 需要用到你的小米账号，安全这根弦一定要绷紧。

1. 尽量只跑在局域网：不要让服务直接暴露到公网。如果必须公网访问，务必开启 HTTP 认证并设置复杂密码，且不要在公共 WiFi 环境下配置账号。
2. 不要绑定摄像头：强烈建议不要在小爱音箱的小米账号下绑定摄像头等隐私设备，账号一旦泄露，后果会很严重。
3. 定期更新：升级 Docker 镜像非常轻松：

docker compose pull docker compose up -d

4. 备份配置：定期备份conf目录，里面保存着你的全部设置。迁移到新设备时，挂载原目录即可无缝恢复。

下一步行动清单

现在，动手的时刻到了。按照这份清单一步步走，很快你就能享受语音点歌的快乐：

1. 克隆项目：git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic
2. 部署容器：按照本文的 Compose 配置启动服务
3. 绑定音箱：设置页输入小米账号，勾选你的设备
4. 导入音乐：把音乐文件放进 music 目录，或者直接用语音让小爱下载
5. 体验指令：从"播放歌曲+歌名"开始，逐步尝试歌单、收藏、定时任务
6. 探索进阶：试试插件、网络电台、多设备协同

音乐是生活的背景音，智能是时代的快捷键。当它们在小爱音箱里相遇，你只需要开口，剩下的交给 XiaoMusic。愿从今晚开始，每一句"播放歌曲"都能得到最动听的回应。

让传统与现代结合，黑胶情怀遇上智能科技

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