企业官网建设流程全解析

XiaoMusic 教程：小爱音箱免费解锁音乐播放，语音控制 5 分钟跑通

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

对小爱同学说"播放周杰伦的晴天"，音箱会把歌下载到本地曲库然后直接放出来，不用会员。XiaoMusic 是一个用 yt-dlp 下载音乐到本地曲库、再让小爱音箱播放的开源工具，适合手里有小爱音箱、想免费听歌的人。

这篇教程按实际使用顺序走一遍：先看部署完成后的效果，再把它跑起来，然后完成配置，最后是语音口令和进阶用法。

🎧 先听效果：部署完成后能干什么

说"播放周杰伦的晴天"时，它的处理顺序是：先查本地音乐目录，有就直接播；没有就用 yt-dlp 抓取资源，下载到音乐目录后接着播放。第一次听需要等下载，之后都从本地秒播。

你还能在 Web 控制台里管理曲库：浏览歌曲、切换设备、调整播放模式和音量。

原理并不复杂：XiaoMusic 跑在你的局域网里，用小米账号拉取音箱的语音对话记录，识别到播放口令后找到对应歌曲，把播放链接发给音箱。音箱的使用体验不变，只是"歌从哪来"被换掉了。

🐳 5 分钟跑通部署

用 Docker 部署（推荐）

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

两个挂载目录分别存放音乐和配置，建议分开。目录不存在会报错，先在宿主机执行mkdir -p /xiaomusic_music /xiaomusic_conf建好。58090 是本机端口可以换，8090 是容器端口，别动。启动成功后，浏览器打开http://你的服务器IP:58090进入 Web 后台。

用 pip 或源码安装

不想用容器的话，先pip install -U xiaomusic，把 config-example.json 复制成config.json填入自己的信息，再用xiaomusic --config config.json启动。想跑源码的话，用git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic获取代码，按 README 里开发指南的步骤装好依赖，pdm run xiaomusic.py启动。

首次配置：只需要三步

1. 填小米账号密码：设置页带*的项必填，保存后就能看到设备列表。
2. 打开语音口令开关：主页的【获取对话记录】开关默认关闭，不开它音箱不会响应任何口令，这是新手最常踩的坑。
3. 换一个 TTS 音色：建议选 Edge-TTS 音色，避免 TTS 登录失败导致语音提示音失效。

控制台布局如下图：左侧是设备控制、播放列表、账号设置、设置四个入口，中间区域是歌曲列表，可以直接点击播放：

语音口令清单：对小爱说什么

• 说"播放周杰伦的晴天"，播放指定歌曲，本地没有就先下载
• 说"播放歌曲"，从本地曲库放歌；"下一首""上一首"切换曲目
• "随机播放""全部循环""单曲循环"随时切换播放模式
• 说"播放歌单流行音乐"，播放对应目录的歌单
• "加入收藏""取消收藏"，把当前歌曲加入或移出收藏歌单
• "关机"或"停止播放"，停止当前播放

还有个隐藏玩法：说"播放歌曲小猪佩奇的故事"，它会先下载故事音频再播放，家里有小孩会很实用。口令词可以在配置文件的key_word_dict里改，不局限于默认的"播放歌曲"前缀。

⚙️ 进阶用法：三个值得试的玩法

网络歌单与电台

除了本地曲库，还可以配置 JSON 格式的网络歌单，支持电台和 m3u8 链接，也支持直接填别人分享的歌单 URL 一键加载。手上有 m3u 电台文件的话，粘贴到内置的 m3u 转换工具 转成 JSON 再保存即可。格式和用法详见如何配置网络歌单与如何添加 m3u 格式文件的电台。

自定义口令与插件

在配置文件的user_key_word_dict里加自己的词，比如把"晨间唤醒"映射到一个播放命令，每天说"小爱同学，晨间唤醒"就放背景音乐。plugins/ 目录提供 JS 插件运行环境，可以写脚本扩展自己的口令逻辑。

定时任务与多设备

配置项支持 crontab 格式定时任务，比如每天固定时间开始播电台。家里有多台音箱时，可以在后台把设备分组一起播，也可以切换设备单独播。

音箱没反应时：常见问题排查顺序

后台看不到设备

日志出现 Login Failed 基本是账号问题：先确认账号密码没填错，关掉本地代理重试，还不行就去米家 App 或 mi.com 官网退出重新登录。日志报 DNS 解析错误的话，把宿主机的 DNS 改成223.5.5.5再重启容器。

网页能播、语音不灵

按顺序查：1）【获取对话记录】开关是否打开；2）口令前缀是否正确，默认必须带"播放歌曲"前缀，光说"播放音乐"不识别；3）首次保存设备 did 后需要重启一次容器。

日志显示播放中却没声音

重点查hostname配置：必须是音箱能访问到的局域网 IPv4 地址，不能填localhost或 IPv6；如果你把 8090 端口映射改了，其他参数要同步改。部分触屏型号可以试着打开【型号兼容模式】。更多报错日志与解法见 FAQ 问题集合。

开始之前，几个提醒

• 安全：后台如果暴露到公网，一定要开启密码登录并设强密码，公共 WiFi 下别用这套工具，小米账号密码可能泄露。
• 格式兼容：本地音乐支持 mp3、flac、wav、ape、ogg、m4a；L05B、L05C 等部分型号放不了 flac，可在后台打开【转换为 MP3】。
• 维护状态：README 已注明项目停止维护，作者建议迁移到社区接力项目，想要长期更新的话要心里有数。
• 所有配置项的完整说明见文档汇总。

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