小爱音箱秒变私人点歌台XiaoMusic 完整部署实战指南【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic音箱买回家两年我最大的抱怨只有一句问它播放孙燕姿的《天黑黑》它永远回答暂时没有找到这首歌。内置曲库残缺、版权下架、热门翻唱版本错乱让家里那台本应智能的小爱音箱沦为了只会报天气的摆设。直到我遇到 XiaoMusic——一个把 yt-dlp 下载能力与小爱音箱语音控制打通的开源工具才真正实现了说一句就播而且播的是我自己收藏的音质版本。本文从零到一完整演示部署过程全程可复制、可落地。XiaoMusic 一句话解释它是一款部署在你电脑或 NAS 上的轻量服务替小爱音箱接住播放某首歌这类语音口令先在本地音乐库或网络上把音频准备好再推送给音箱播放。先给结论一行命令就能跑起来如果你只想快点看到效果这是最短路径Docker 环境已就绪的前提下mkdir -p /xiaomusic_music /xiaomusic_conf docker run -d --name xiaomusic --restart always \ -p 58090:8090 \ -v /xiaomusic_music:/app/music \ -v /xiaomusic_conf:/app/conf \ docker.hanxi.cc/hanxi/xiaomusic启动成功后浏览器打开http://你的设备IP:58090就能看到管理界面在网页里填入小米账号和密码保存即可获取你名下的小爱音箱列表。后面我会逐步拆解这条命令的每一个参数以及比这更省心的 compose 写法和配置细节。为什么需要这样一套工具三种方案的对比在决定用 XiaoMusic 之前我先后试过三种思路各有各的坑方案效果短板让小爱音箱连蓝牙播放手机音乐能用但每次都要手动连接不能语音点歌谈不上智能用音箱自带的QQ音乐/网易云热门歌还行版权歌单残缺免费版广告多不能放本地无损公网音乐接口直接推流曲库全稳定性差经常失效还要维护接口XiaoMusic 的思路完全不同它不做曲库只做翻译官 搬运工。语音口令进来后它解析出歌曲名和歌手名先在挂载的本地音乐目录里找找不到就用 yt-dlp 去网络音源下载最后通过小米服务把音频推给音箱。本地有就用本地的本地没有才去下载音质和曲库都掌握在自己手里。部署前需要准备什么动手之前先确认三件事一台能长期开机的设备NAS、旧笔记本、云服务器都行只要能跑 Docker。项目官方文档支持 amd64、arm64、armv7 三种架构常见的群晖、威联通、树莓派都没问题。一只小爱音箱L06A、L07A、L15A、L16A、L17A、LX05、LX06 等主流型号都在官方支持列表里触屏版和 Sound 系列也能用。一个小米账号账号需绑定你的音箱部署时要用它登录获取设备列表。目录规划建议把音乐和配置分开存放。音乐目录会越来越大单独挂载方便备份配置目录里是账号信息和你自定义的语音口令单独挂载方便迁移。Docker Compose 部署每个参数的作用都讲清楚推荐用 compose 而不是裸docker run因为配置是声明式的重装、升级、迁移都省心。新建一个docker-compose.ymlservices: xiaomusic: image: docker.hanxi.cc/hanxi/xiaomusic # 国内镜像拉取速度快 container_name: xiaomusic # 容器名字方便 docker logs 查看 restart: always # 开机自启 崩溃自动拉起 ports: - 58090:8090 # 宿主机58090 - 容器8090 volumes: - /xiaomusic_music:/app/music # 宿主机音乐目录 - 容器音乐目录 - /xiaomusic_conf:/app/conf # 宿主机配置目录 - 容器配置目录逐项说明58090:8090左侧 58090 是你访问管理页面的宿主机端口可自行修改右侧 8090 是容器内服务端口不要动。/app/music容器内固定的音乐目录你往宿主机/xiaomusic_music里丢 MP3、FLAC、WAV 等文件服务端立刻能扫描到。/app/conf容器内固定的配置目录网页上保存的设置会以 JSON 形式落盘在这里备份它等于备份了全部配置。如果宿主机上还没有这两个目录先执行mkdir -p /xiaomusic_music /xiaomusic_conf避免挂载时报找不到目录。保存后一条命令拉起docker compose up -d查看运行状态和日志docker ps | grep xiaomusic docker logs -f xiaomusic不想用 compose 也没关系开头那行docker run与上面完全等价。二者选其一即可。首次配置三分钟完成账号绑定服务起来后访问http://你的IP:58090进入设置页面。带*号的是必填项其余保持默认即可填入小米账号和密码保存。这一步服务会去小米服务器换取访问凭证拿到你的设备列表。刷新页面在设备区域勾选你要控制的小爱音箱再次保存。回到首页如果看到你的音箱在线说明绑定成功。⚠️安全提醒小米账号密码会明文保存在配置文件里请务必只在自家局域网使用如果一定要公网访问务必开启 HTTP 认证并设置高强度密码且不要把这个账号绑定摄像头等敏感设备。配置落盘后你可以打开conf目录里的配置文件看看结构里面有account、password、mi_did等字段。项目根目录的 config-example.json 是完整的参数样例逐行对照就能搞清楚每个配置项的含义。效果验收这些语音口令现在都能用了绑定完成后直接对着小爱音箱说话试试播放歌曲 周杰伦 晴天—— 按歌手歌名精确点歌播放本地歌曲—— 只从本地音乐库随机播放播放歌单 轻音乐—— 按目录名播放整个歌单下一首 / 上一首—— 切歌单曲循环 / 全部循环 / 随机播放—— 切换播放模式30分钟后关机—— 定时停止播放加入收藏 / 取消收藏—— 管理收藏歌单第一次点播不存在的歌时服务会调用 yt-dlp 去网络音源下载稍等片刻即开始播放。下载好的文件缓存在音乐目录里下次再点同一首就是秒播。深入配置把语音指令调教成你想要的样子自定义口令映射语音口令本质是一张人话 → 命令的映射表。默认配置里下一首对应play_next停止播放对应stop。你可以完全按自己的习惯改{ user_key_word_dict: { 切歌: play_next, 不听了: stop } }在设置页面的用户自定义口令区域填入类似内容保存即可生效。注意口令匹配有优先级顺序建议把更具体、更长的口令排在前面避免停止和停止播放这类短词先命中。关键开关与它们的用途配置项作用建议convert_to_mp3把不兼容格式转成 MP3 再播放旧型号音箱如 L05B、L05C建议开启enable_fuzzy_match模糊匹配说错一两个字也能找到歌默认开启阈值 0.6可调disable_download禁止自动下载网络音源只想用本地库时开启enable_cmd_del_music允许语音删除歌曲家有小孩慎开防止误删music_path_depth扫描本地音乐的子目录深度默认 10 层够用exclude_dirs跳过不扫描的目录名建议加入tmp避免扫描缓存定时任务与节假日联动如果你想让音箱充当闹钟或助眠工具项目内置的定时任务模块 xiaomusic/crontab.py 支持标准 cron 表达式还额外支持#workday和#offday两个特殊标记——配合 xiaomusic/holiday.py 里的节假日数据可以实现工作日早上 7 点播新闻节假日不打扰这种聪明规则0 7 * * 1-5 #workday 播放早间歌单 0 22 * * * #offday 播放助眠音乐多设备与网络歌单家里有多只音箱在网页设备列表里全部勾选即可同时托管。还想听网络电台或别人分享的歌单项目支持 JSON 格式的网络歌单也自带了把 m3u 电台文件转换成 JSON 的网页工具转换后填进music_list_url配置即可。常见问题排查速查以下是我在真实部署中遇到、且高频出现的四类问题按现象 → 原因 → 解法整理问题 1网页打不开端口无响应先确认容器在跑docker ps。若容器不断重启看日志docker logs xiaomusic找报错若只是端口不通检查宿主机防火墙是否放行了 58090以及 58090 是否被其他进程占用ss -tlnp | grep 58090。问题 2能打开网页但设备列表是空的通常是小米账号登录态失效或账号下没有绑定音箱。先在网页上重新保存一次账号密码刷新凭证仍不行就登录小米自家的米家 App 确认音箱绑在同一个账号下。注意账号密码含特殊字符时粘贴到网页输入框里可能被截断可以改为在配置 JSON 文件里直接编辑再重启容器。问题 3点歌后一直不出声日志显示下载失败yt-dlp 下载音源依赖网络环境如果你的设备访问外网不畅可配置代理在设置里填入proxy地址。另外确认search_prefix是bilisearch:默认——如果被误改成了ytsearch:某些网络环境下会超时。问题 4本地歌单里明明有歌却提示找不到检查文件名格式默认按歌手名 - 歌名.mp3或歌名.mp3解析太复杂的命名会影响匹配。开启enable_fuzzy_match可缓解另外确认文件确实在挂载的 music 目录下且文件扩展名在支持列表内mp3/flac/wav/ape/ogg/m4a。个别旧型号音箱不支持 flac此时打开转换为 MP3开关。排查时最有用的手段是网页设置底部的下载日志文件按钮导出的日志会记录口令解析、设备推送、下载失败等全过程信息。提交问题给社区前记得先确认日志里没有账号密码等敏感内容。更进阶的玩法插件扩展与多端控制XiaoMusic 不只是一个播放器它的口令引擎支持调用自定义插件。项目仓库的 plugins/ 目录里内置了几个示例code1.py演示了如何写一个自定义口令处理函数httpget.py和httppost.py则演示了如何让音箱去请求外部 HTTP 接口——这意味着一句打开客厅灯这种口令理论上也可以由你自由扩展把它变成家庭场景的万能语音开关。社区还围绕它衍生了不少周边玩法手机 App、微信小程序、安卓 TV 客户端、Web 播放器主题等都能让你在不用音箱的场合继续管理音乐库。下一步行动清单如果你决定动手按这个顺序走完就能顺利跑起来确认环境Docker 已安装音箱已绑定小米账号且与部署设备在同一局域网。创建目录mkdir -p /xiaomusic_music /xiaomusic_conf丢几首 MP3 进去验证本地库。编写 compose 文件并启动确认docker ps显示容器正常运行。网页绑定账号填入小米账号密码 → 刷新 → 勾选音箱 → 保存。验收语音指令先试播放本地歌曲再试播放歌曲 歌手名 歌名。按需调教自定义口令、开启模糊匹配、配置定时任务。养成备份习惯定期备份conf目录升级镜像前先docker compose pull再up -d。如果只记住三件事目录分开挂载、账号只在局域网配置、日志文件是排查故障的第一入口。搞定了这三条你家的音箱就不再是只会报天气的摆件而是一台真正听懂你话的私人点歌台了。祝你享受这份自己动手换来的自由听歌体验——毕竟音乐本来就应该按你喜欢的样子播放。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考