企业官网建设流程全解析

三步解放小爱音箱：XiaoMusic 免费听全网音乐的完整配置指南

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

周末早晨，你对音箱说"小爱同学，播放周杰伦的《晴天》"，得到的回应却是"抱歉，这首歌需要开通音乐会员"。孩子要听的童话故事、你收藏夹里的冷门老歌，几乎处处碰壁。其实不用开会员，也不用买 U 盘——开源项目XiaoMusic的思路很直接：它把小爱音箱的语音指令截下来，用 yt-dlp 把歌免费下载到本地，再让音箱直接播本地文件。部署一次，以后喊歌名就行。

📋 价值速览：这个项目值不值得你花 20 分钟

先给你一张"方案卡片"，看完再决定要不要折腾：

它不是又一个"播放插件"，而是把小爱音箱从"平台点播器"改造成"你自己音乐库的遥控器"。

🔍 它是怎么做到的：拆成三件事讲清楚

XiaoMusic 的核心代码在 xiaomusic/ 目录，但你要理解的其实只有三个环节，我一个个打比方。

1. 听并拦截：一个会看"关键词表"的秘书

你每说一句"小爱同学"，指令都会经过 XiaoMusic。它手里有一张关键词映射表（配置项key_word_dict），比如"播放歌曲"→ 触发搜索播放、"下一首"→ 切歌、"加入收藏"→ 收藏。这就像给小爱派了个贴身秘书：秘书先听完你要什么，能办就自己办，办不了再转交给原系统。指令解析逻辑在 xiaomusic/command_handler.py。

2. 抓并保存：yt-dlp 这个"全能搬运工"

本地没有这首歌怎么办？XiaoMusic 调用 yt-dlp 引擎从多个音乐平台把音频抓下来，默认存成 mp3，按歌名存进你的音乐目录。一次下载，永久可用——下次再点同一首歌，直接走本地，几乎秒播。下载与在线播放相关逻辑在 xiaomusic/online_music.py。

3. 管并播放：本地音乐库 + 网页控制台

下载下来的文件就躺在你指定的目录里，XiaoMusic 会自动扫描建库。你打开http://NAS_IP:58090的网页控制台（服务入口 xiaomusic/api/app.py），能切分类、搜歌曲、删歌曲、切换设备。它同时支持播放你自己目录里已有的 flac、ape 等无损文件——等于把你现成的音乐收藏也一并"激活"了。

🐳 部署三步走：从一条 Docker 命令到出声

部署过程真正的门槛只有"目录映射"这一个点，下面逐步说清。

第一步：Docker 一条命令启动

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

两个-v是新手最容易错的地方：/xiaomusic_music是主机上放歌的目录（可以换成你自己的路径），/app/music是容器内固定路径，不要改；58090是你在家里访问的端口，8090是容器端口，也不要改。国内拉镜像慢的话，把镜像名换成docker.hanxi.cc/hanxi/xiaomusic即可。

第二步：网页里填两项必填配置

浏览器打开http://你的IP:58090，在设置页只需关心带*的项：

• 小米账号 + 密码：唯一必须填的东西，保存后设备列表才会出来
• 音乐目录：Docker 部署下默认已映射好，源码部署时建议写成绝对路径，避免权限问题

其余几十项配置（代理、定时任务、TTS 提示语等）都有示例默认值，参考 config-example.json，用不到就不动。

第三步：源码安装（备选方案）

想自己改代码的话，用源码跑：

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic cd xiaomusic ./install_dependencies.sh pdm install pdm run xiaomusic.py

或者更省事，直接pip install -U xiaomusic再执行xiaomusic --config config.json，配置文件同样参考config-example.json。

⚖️ 改造前 vs 改造后：小爱音箱到底变了什么

几个可以写进笔记的实测口径：

• 设备覆盖：官方已测试 20+ 款型号，从小爱音箱 mini 到 Xiaomi Sound Pro，含触屏版
• 格式支持：mp3 / flac / wav / ape / ogg / m4a 六种，本地扫描 + 下载均可
• 二次播放延迟：歌曲已在本地时无需任何网络请求，响应只取决于局域网快慢
• 口令种类：播放、切歌、三种循环模式、歌单点播、收藏/取消收藏开箱即用

🎛️ 玩法进阶：让音箱真正"懂你"

基础功能跑通后，下面三个玩法是社区里被用得最多的，每个都给你配了具体例子。

自定义语音口令：把场景说成一句话

配置文件里的user_key_word_dict允许你给任意口令绑定动作，甚至直接调用 Python 插件函数。比如：

"user_key_word_dict": { "晨间唤醒": "exec#code1(\"播放晨间音乐\")", "睡前安眠": "exec#code1(\"播放白噪音\")" }

插件怎么写？看仓库自带的 6 行示例 plugins/code1.py——拿到当前设备号，发一句 TTS 语音，就这么简单。从此"小爱同学，晨间唤醒"就能触发你编排的任何组合动作。

多设备协同：客厅卧室各放各的

控制台右上角就是设备切换器，配置里的devices和group_list还能把多台音箱编组。典型用法：客厅音箱放背景音乐、卧室音箱定时放睡前故事（配合定时任务配置项crontab_json）、书房音箱只播专注歌单——同一套音乐库，不同房间不同场景。

网络歌单：电台和在线歌曲一起点

设置页支持填 JSON 歌单（电台 + 网络歌曲），也支持直接粘贴别人分享的链接一键导入。玩法文档在 docs/issues/78.md，配合内置的 m3u 电台文件转换工具 xiaomusic/static/default/m3u.html，可以把电台的 m3u 文件秒变网络歌单；多个歌单还能用 xiaomusic/static/default/merge/index.html 合并成一个。

⚠️ 避坑手册：部署前必看的 5 个高频问题

Q1：网页里保存了账号密码，设备列表却出不来？先确认账号密码是否输错（建议重新完整填写一遍再保存）；再确认音箱和运行 XiaoMusic 的机器在同一局域网、网络稳定。仍不行就按 Q4 下日志排查。

Q2：某首歌下载失败或没有资源？平台版权会动态变动，同一首歌换个搜索关键词、或调整配置里的search_prefix（搜索源前缀）再试，多数情况能绕过去。

Q3：flac 放不出声音？L05B、L05C、LX06、L16A 这几个型号不支持 flac 格式。设置页打开【转换为 MP3】和【型号兼容模式】两个开关即可。

Q4：出问题了去哪里看日志？提 Issue 要注意什么？Web 设置页底部有【下载日志文件】按钮。注意：上传或贴日志前，先检查并删掉里面的账号密码信息，再连同日志去仓库提 Issue，定位会快得多。

Q5：会影响音箱原有功能吗？不会。XiaoMusic 只接管它识别的自定义口令，"放新闻""定闹钟"这类原有功能照常工作，互不冲突。

🛡️安全提醒：如果要把 XiaoMusic 暴露到公网，务必在设置里开启密码登录并设复杂密码，且不要在公共 WiFi 下使用；另外强烈建议不要用绑定了家用摄像头的小米账号来跑这个项目——账号一旦泄露，风险远不止音乐。

🚀 现在就动手：你的音箱该解锁了

部署只需要 20 分钟：一条 Docker 命令、一个小米账号、一句"播放歌曲"，全网音乐库就是你的了。

• 遇到报错：先翻 docs/issues/index.md 的问题集合，90% 的新手坑都有现成答案
• 想深入玩法：网络歌单看 docs/issues/78.md，源码入口在 xiaomusic/
• 发现 bug 或有新想法：去仓库提一个 Issue，也欢迎提交前端美化或功能开发的贡献

现在就去 NAS 上敲下那条docker run，然后回家喊一句"小爱同学，播放歌曲"试试。

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