企业官网建设流程全解析

xiaomusic 在线搜索快速上手：语音点歌与配置避坑

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

xiaomusic 的「在线搜索」扩展让小爱音箱不依赖本地曲库，直接在线搜到歌曲并立刻播放：可以语音口令点歌，也可以网页搜索后推到音箱，或干脆在浏览器里听。本文带你按顺序完成这些事：先把一种生态跑通，再在 MusicFree 插件与 LX Server 接口之间做选型，最后掌握搜索格式、语音口令、进阶设置和一份排错清单。

五步把 xiaomusic 在线搜索跑起来

先走配置量最小的 LX Server 路线，拿到正反馈再谈其他。

1. 在服务器上部署好 LX Sync Server，确认可访问的接口地址（形如http://127.0.0.1:9527/api）；
2. 打开在线搜索后台配置页，在「接口生态」处切到 LX Server 接口；
3. 填入base_url，点「接口测试」（V1.1.2+ 提供）验证连通性；
4. 回到「小爱音箱设置面板」完成音箱绑定，没有绑定音箱推送就不工作；
5. 在搜索页输入歌曲名 - 艺术家，确认结果能推到音箱播放。

坑点｜拿不准生态先跑通 LX Server：它只有一个地址必填项，还能一键自检，跑通后再按需要换 MusicFree。

选对接口生态：MusicFree 插件还是 LX Server

两条路线同一时间只有一条生效：配置项back_conf_info.api_type里1代表 MusicFree 插件、2代表 LX Server 接口。切换时前端会弹确认，因为两套配置各管各的字段，切过去等于放弃另一边的已有设置。

MusicFree 路线的关键点：

• 订阅插件源：编辑地址后点「更新订阅」，系统校验返回的 JSON 含plugins数组再批量下载；
• 手动上传只接受.js文件，文件名不能占用ALL、OpenAPI等保留字段，同名不可重复；
• 在线导入只需粘贴一个http(s)://插件地址；
• 权重规则：启用列表里排得越靠前权重越高，前 9 个插件有效，第一名权重 9 分，逐位递减。

LX Server 路线的关键点：

• base_url是唯一必填项；认证（V1.1.3+）另填x-user-name与x-user-token，请求时自动带上这两个头；
• 接口测试（V1.1.2+）会请求${base_url}/music/config，校验player.enableAuth和user.enablePublicRestriction字段来确认是合法接口；
• 播放保障做得比较完整：音质按master → flac24bit → flac → 320k → 192k → 128k逐级降级，原平台解析失败时按「歌名 + 歌手 + 时长误差 5 秒内」跨平台换源。

坑点｜不建议把 LX Music Sync Server 升到 v1.8.2 及以上，因为该版本起接口加了 Token 限制，需等在线搜索新版适配后再升。

搜索与播放：写准关键词、看懂排序、选对出口

关键词格式：用歌曲名 - 艺术家，后端以第一个-为界拆开歌曲与歌手，匹配准确度明显高于只搜歌名。

聚合与排序：MusicFree 侧并行调用所有已启用插件（每插件限额按数量分摊），LX 侧并行请求所有已配置平台，结果合并后统一排序。优先级固定为：歌曲名匹配度 > 歌手名匹配度 > 平台权重。语音"取第一首"时按分数选：歌名完全匹配 +90、开头匹配 +70、结尾 +50、包含 +30；歌手名命中按 +9/+7/+5/+3 递减。

两个播放出口，按场景取舍：

• 推音箱：适合日常点歌，前提是已绑定音箱；
• 网页端：适合听一些音箱吃不下的音频流。

坑点｜MusicFree 部分插件（如 B 站源）拿到的音频流不被小爱音箱支持，这类资源请改用网页端播放。

另外，后端对在线 URL 有安全校验：内网、回环、链路本地、多播等地址一律拒绝，防止 SSRF，这是设计行为，不用怀疑配置。

开口点歌：两条语音口令和 AI 解析

先做｜进入后台「允许唤醒的命令」，把,singer_play,online_play,加进列表，口令才生效。

语音搜歌单是独立链路（online_playlist_play）：先搜歌单列表、按策略选出最优一个，再拉全量歌曲推给音箱。选哪个歌单由voice_playlist_strategy控制，下一节讲。

AI 口令提取（默认关闭）：在aiapi_info里把enabled设为true、填上api_key即可，能帮你从"我想听那首关于秋天的歌"这类模糊话术里拆出歌名和歌手。接口地址留空时默认走阿里百炼，模型默认qwen-flash；解析失败或 AI 不可用会自动回退到传统的"歌名-歌手"分割，不会卡死。

"aiapi_info": { "enabled": true, "api_key": "你的key", "model": "qwen-flash" }

注意｜只认符合 OpenAI API 规范的接口，其他规范的模型服务暂时用不了。

进阶设置：自动追加、搜单策略、密码锁与歌单转换

密码锁的实际流程：进后台先查GET /api/password/check，返回required: true就弹密码框，验证接口是POST /api/password/verify。忘记密码直接编辑conf/plugins-config.json把password改掉，置空即关闭密码锁。

"password": "", "auto_add_song": true

坑点｜由 LX 歌单转换来的 XM 歌单带_online_lx_前缀，必须把生态切到 LXServer 侧才能使用；配置结构大改的版本升级后，旧conf/plugins-config.json需要删掉重配。

排错清单：常见现象与处理

把生态跑通、口令配好、偏好留all，在线搜索这套功能基本就不会再坑你。想深入实现细节，建议按顺序读这三处：搜索与降级逻辑在xiaomusic/online_music.py，插件沙箱与 LX 请求在xiaomusic/js_plugin_manager.py，全部 REST 接口在xiaomusic/api/routers/plugin.py，后台页面入口是xiaomusic/static/onlineSearch/setting.html。

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