企业官网建设流程全解析

xiaomusic 在线搜索实战：小爱音箱不依赖本地曲库也能在线点歌

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

有没有这种时刻：想听的歌不在本地曲库里，音箱只能尴尬沉默？xiaomusic 在线搜索就是为这个场景准备的：在网页上搜一首歌推给音箱直接播，或者干脆对音箱喊一声"在线播放 江南"，搜索和播放它自己完成。读完这篇，你能独立跑通网页推歌与语音点歌两条链路。

开工前先选边：插件生态 vs 自建接口

先说结论：动手填配置之前，得先把搜索底座定下来。后台的api_type字段只有两个取值：1是 MusicFree 插件，2是 LX Server 接口（结构可参考 xiaomusic/plugins-config-example.json），同一时间只有一套生效。

两条路线的差别，一张表能看明白：

插件版背后的机制值得知道：JSPluginManager（实现在 xiaomusic/js_plugin_manager.py）拉起一个 Node.js 子进程当插件沙箱，Python 端通过标准输入输出收发 JSON 消息。LX 版则把更多事交给服务端，本地侧重播放保障，比如跨平台换源时要求"歌名+歌手一致且时长误差≤5秒"才算同一首歌。

从部署到第一首歌：两条路线的后台填写

最短路径先走一遍：部署并启动 xiaomusic（已有本地曲库可跳过下载环节），在「小爱音箱设置面板」完成音箱绑定，进后台在线搜索配置页（xiaomusic/static/onlineSearch/setting.html）选生态，填好对应参数，搜索页里搜"歌名 歌手"，命中后推送到音箱，或在当前网页直接播放。

切换生态时前端会弹确认框，因为两边配置互不兼容，切了之后旧配置对另一边无效。想好再切。

插件路线（xiaomusic 配置 MusicFree）

1. 编辑订阅地址后点「更新订阅」，系统拉取订阅源 JSON 并批量下载插件；
2. 没有订阅源也可以手动上传本地.js文件，或粘贴一个http(s)://插件地址在线导入；单个插件支持启用、禁用、卸载；
3. 调整启用列表的顺序。排序算法只给前 9 个插件记权重分（权重 = 9 - 排名），顺序就是你的音源偏好。

接口路线（xiaomusic 配置 LX Server）

1. 填入 LX Server 的 API 地址（形如http://127.0.0.1:9527/api），点「接口测试」验证连通性；
2. 服务端开了鉴权的话，补上x-user-name与x-user-token，请求时会自动带上这两个头；
3. 在平台列表里增删tx、kg、kw等搜索平台，全部保留即为聚合搜索。

高级设置四项，按需打开：

• 自动追加歌曲：播放到歌单末尾时自动补同歌手歌曲，默认开启；
• 自动拉取并转换 LX 歌单：每 30 秒同步一次，仅接口版显示；
• AI 口令提取：默认关闭，开启后填接口地址（留空走阿里百炼）、API Key、模型名（默认qwen-flash）；
• 语音搜单策略：default取首条，另有歌曲最多、播放最多、随机可选。

持久化都落在运行目录的conf/plugins-config.json，看懂这几行就够日常维护了：

"back_conf_info": { "api_type": 1 }, "lx_server_info": { "base_url": "", "platforms": { "tx": "小秋音乐" }, "box_play_platform": "all" }, "music_free_info": { "enabled_plugins": [], "plugin_source": { "source_url": "" }, "box_play_platform": "all" }

api_type决定走哪条路，另外两块分别对应两套生态的专属参数。后台还有一把可选密码锁：配置里给password字段填非空值即启用，置空即关闭。

动口点歌：三条口令的分工

开通方法只有一处：在小爱音箱设置面板的「允许唤醒的命令」里，把online_play、singer_play加进白名单，歌单口令online_playlist_play同理。加完，音箱就多出了直接开口的能力。

• online_play：说"在线播放 林俊杰 江南"，后端搜索后给候选逐条打分，歌名完全匹配、开头匹配、包含匹配分层计分，歌手名同理，取最高分那条直接播；
• singer_play：说"播放歌手 周杰伦"，把该歌手的热歌建成临时歌单顺序播放；
• online_playlist_play：说"在线歌单 某某榜单"，走独立链路，先搜歌单列表，按你选的策略挑一个最优，拉全量歌曲推给音箱。

背后逻辑都在 xiaomusic/online_music.py 里，想看打分细节可以从_search_top_one读起。

进阶开关：把偏好固定下来

三个开关，分别解决"说不准歌名""想固定音源""不想占音箱"三种情况。

AI 口令提取⚡：默认关闭。开启后，"我想听那首关于秋天的歌"这类模糊说法会先经大模型解析出歌名和歌手再搜索；解析失败或 AI 不可用时自动回退到"歌名-歌手"的-分割法，功能不会断。注意模型接口需符合 OpenAI API 规范。

口令搜索偏好：配置字段叫box_play_platform，填某个平台代号（如tx）即该平台优先，填all保持聚合。两种生态各有一份此字段，互不干扰。

网页端兜底播放：搜索结果不推音箱、直接在搜索页播放即可。部分插件（如 B 站源）拿到的流格式小爱可能播不了，这类资源用网页端播放最稳。

排障清单：症状、原因与解法

五个高频卡点，按"症状 → 原因 → 解决"对号入座。

LX 接口版搜得到但播不出来→ LX Music Sync Server 在 1.8.2 之后对接口加了 Token 限制，与当前版本不兼容。停留在 1.8.2 之前的服务端版本，或看 docs/issues/811.md 里的处理方案。

AI 口令提取没生效→ 逐一核对aiapi_info里enabled是否为true、api_key是否为空、模型接口是否符合 OpenAI 规范。接口地址留空即可走默认百炼通道。

语音喊了没反应→ 口令没在「允许唤醒的命令」白名单里。确认列表包含singer_play与online_play。

LX 歌单转出来的歌单放不了→ 这类歌单（_online_lx_前缀）只在 LX Server 生态下生效。把接口生态切换回 LX Server 再播放。

升级后台后配置页行为不对→ 配置结构在部分版本（如 V1.1.1）有过重构。删除旧的conf/plugins-config.json，重启后在网页端重新配置。

另有一个安全细节：后端对所有在线播放地址做校验，拒绝内网、回环、多播等地址，防止 SSRF，这部分逻辑在_make_request_with_validation中。

想深入看的资源

• 在线搜索核心业务（搜索/聚合/直链/降级/AI 解析）：xiaomusic/online_music.py
• 插件沙箱与 LX 接口管理：xiaomusic/js_plugin_manager.py
• 后台配置页及相关脚本：xiaomusic/static/onlineSearch/
• 配置文件模板：xiaomusic/plugins-config-example.json
• LX 接口版搜得到播不出的完整讨论：docs/issues/811.md
• LX 歌单同步方案讨论：docs/issues/807.md

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