企业官网建设流程全解析

xiaomusic 在线搜索怎么接？两条路线一步步配好，音箱随时点歌

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

对着小爱音箱说一句"在线播放 林俊杰 江南"，音箱却只回一句找不到歌？或者你在网页搜索框里敲了半天，列表空空如也——多半是 xiaomusic 的在线搜索还没接好搜索源。这个扩展不用本地曲库，直接去互联网上搜歌、把结果推给音箱播或网页直接听，核心逻辑集中在 在线音乐服务源码，搜索源管理则由 JS 插件管理器 负责。整个接入过程只需要选一条路线、填几个参数，配好之后语音点歌、网页搜歌都能直接用。

动手前的 3 分钟检查清单

在动配置之前，先把下面几件事过一遍，能避开后面 80% 的"配了不生效"问题：

• 音箱已绑定：要用"推给音箱播"，必须先在「小爱音箱设置面板」完成设备绑定，否则搜索结果只能在网页听。
• 口令白名单：语音点歌依赖两个口令，检查【允许唤醒的命令】列表里是否包含singer_play和online_play，缺一个对应功能就哑火。
• LX 版本：如果打算走 LX Server 路线，注意 LX Music Sync Server v1.8.2 之后接口加了 Token 限制，该版本先别急着升，等 onlineSearch 新版适配。
• 旧配置清理：如果你从较早版本升级过来，配置文件结构已经重构过，直接删掉/conf/plugins-config.json再重启服务，在网页端重新配一遍最省事。

先想清楚：走 LX Server 还是 MusicFree 插件

两条路线功能上能做的事一样——聚合搜索、语音点歌、网页播放，区别只在"歌从哪儿来"：

一句话推荐：已经跑着 LX Sync Server 的，直接选 LX，五分钟接完；没有部署习惯、只想要现成插件资源的，选 MusicFree。两条路线互斥，同一时间只有一条生效，配置文件里对应api_type字段：1 = MusicFree 插件，2 = LX Server 接口。切换时后台会弹确认框——因为两边配置项（插件列表 vs 平台列表）互相不兼容，切错要重新填。

5 分钟接好 LX Server 接口

这节解决"我有 LX 服务端，想让 xiaomusic 用上它"的问题。

1. 打开哪里：在线搜索后台配置页（setting.html），在「接口生态」区域选择 LXServer 接口。
2. 填什么：接口地址填你的 LX 服务 API 入口，典型形如http://127.0.0.1:9527/api。如果服务开了鉴权，把x-user-name和x-user-token一并填上，之后所有请求会自动带这两个请求头。
3. 点什么：先点「接口测试」。后端会请求${base_url}/music/config并校验返回里有没有player.enableAuth、user.enablePublicRestriction字段，通过即说明地址合法。然后在「平台管理」里添加要参与搜索的平台，常用的五个：tx小秋、kg小枸、kw小蜗、wy小芸、mg小蜜。加几个平台，搜索时就并行请求几个再合并结果。
4. 如何验证生效：回搜索页搜一首歌，列表顶部应能看到来源平台标签；再对音箱说一句"在线播放"口令，能出声就通了。

机制上只补两句：播放时系统先查${base_url}/music/cache/check缓存，未命中再走进度接口加${base_url}/music/url解析直链；音质按master > flac24bit > flac > 320k > 192k > 128k的顺序优先选你偏好的档位，直链解析失败自动降档，原始平台挂了还会按"歌名+歌手+时长误差 5 秒内"跨平台换源。这些都不用你管，知道它不会轻易失败就行。

手动装好 MusicFree 插件

这节解决"我不想部署服务端，想用现成插件搜歌"的问题。

1. 打开哪里：同一后台配置页，「接口生态」选 MusicFree 插件，下面出现「插件源配置」区域。
2. 填什么 / 点什么，三种导入方式任选：
   • 订阅更新：填入插件源地址，点「更新订阅」。系统会拉取该地址的 JSON，校验其中有plugins数组后批量下载插件；
   • 手动上传：只收.js文件，且文件名不能用ALL、all、OpenAPI、OPENAPI这几个保留名，同名插件也不能重复传；
   • 在线导入：直接粘一个http(s)://的插件地址，拉单个插件。
3. 管插件：对已装插件可以做启用、禁用、卸载；后台也留了 MusicFree 官方插件市场的直达入口。
4. 如何验证生效：把要用的插件启用，回搜索页搜一首歌，结果里带上该插件的平台标签即生效。插件文件落在配置目录的js_plugins/下，元数据记在配置文件的music_free_info节点里。

⚠️ 一个容易踩的点：搜索结果排序按【歌曲名匹配度】>【歌手名匹配度】>【插件权重】走，插件权重就是启用列表里的先后顺序，只有前 9 个插件的权重有效，排得越靠前分数越高。想优先出某个源的歌，把它往前挪就行。

从能用到好用：语音口令与自动连播

搜索通了之后，这几个开关能让体验从"能用"跨到"顺手"。

语音点歌。两条口令直接对音箱说：

打分规则是歌名完全匹配 +90、开头 +70、结尾 +50、包含 +30，歌手名按 +9/+7/+5/+3 递减，取最高分。所以"歌名-歌手"的写法（如江南-林俊杰，以第一个-分割）能显著提高命中准确度。另外还有一条搜歌单口令online_playlist_play：搜出歌单列表后按策略选一个，拉全量歌曲推给音箱播。

AI 智能口令提取。默认关闭。开了之后，模糊指令（"我想听那首关于秋天的歌"）会先丢给大模型解析出歌名和歌手再搜，失败或不可用时自动回退到传统的歌名-歌手分割。在高级设置里填接口地址（留空默认阿里百炼）、API Key、模型名（默认qwen-flash）。❗ 注意接口必须符合 OpenAI API 规范，其他协议的模型接不上。

自动追加同歌手。默认开启。播放到歌单最后一首时，自动搜同歌手的新歌续上，适合躺平时挂机连播。注意它只对「全部播放」（即全部循环）模式生效——在线点播创建的歌单默认就是这个模式。

另外两个策略开关：口令搜索偏好平台（box_play_platform，填all表示全平台聚合）和语音搜单策略（default取首条 /max_songs歌曲最多 /max_plays播放最多 /random随机），都在高级设置里，默认值日常够用。

conf/plugins-config.json 里最常动的几处

整个扩展的持久化配置都在这一个文件里（首次启动由 配置文件模板 生成）。只挑最常改的说：

{ "api_type": 1, "base_url": "http://127.0.0.1:9527/api", "x-user-name": "", "x-user-token": "", "auto_convert": false, "auto_add_song": true, "aiapi_info": {"enabled": false, "api_key": ""}, "box_play_platform": "all", "password": "" }

（以上为各节点关键字段节选，完整结构见模板文件。）

• api_type：改成 2 就走 LX 路线，改 1 走 MusicFree。改错会导致后台页面和实际搜索对不上。
• base_url/x-user-name/x-user-token：LX 三件套，地址填错一切白搭；服务开了鉴权却不填头，请求会被拒。
• auto_convert：打开后每 30 秒自动把 LX 歌单转成 xiaomusic 歌单（仅 LX 路线显示该选项）。❗ 转出来的歌单带_online_lx_前缀，只有生态停留在 LXServer 状态下才能使用。
• auto_add_song：自动追加同歌手歌曲的开关，设false即关闭。
• aiapi_info：enabled设true且api_key非空，AI 口令提取才启动。
• box_play_platform：两条路线各有一份，语音口令搜索时优先哪个源，all是全部聚合。
• password：非空即开启后台密码锁。进后台会先过GET /api/password/check，验证走POST /api/password/verify；忘记密码就编辑此字段，置空即解锁。

问题自救：现象 → 原因 → 处理

• 配好 LX 接口搜得到歌但播不出：先确认服务端版本不是 v1.8.2 之后（Token 限制），再点一次「接口测试」看连通性；仍不行参考 issue 811 的处理方案。
• 想同步平台歌单到音箱播：LX 路线下开auto_convert做 LX 歌单转 XM 歌单，前提生态停在 LXServer；更多讨论见 issue 807。
• AI 口令提取不生效：检查aiapi_info的enabled是不是true、api_key是否为空，以及模型接口是否遵循 OpenAI API 规范，三者缺一即静默回退到普通分割。
• B 站等部分源的歌音箱放不了：MusicFree 个别插件拿到的音频流格式小爱不支持，这类资源改用网页直接听。
• 搜同一首歌出来一堆结果：在关键词里用-把歌名和歌手分开写，比如江南-林俊杰，匹配度立刻上来。
• 播放链接突然失效：这是保护机制在起作用——在线 URL 校验会拒绝内网、回环、链路本地、多播等地址（SSRF 防护），链接解析不过关时会原样返回，此时换个源或平台再试。
• 改了高级设置里"自动追加歌曲"没反应：确认当前播放模式是「全部播放」，该功能只在全部循环模式下工作。

资源入口

• 在线搜索核心业务（搜索、聚合、直链解析、换源降级、SSRF 防护）：xiaomusic/online_music.py
• 插件沙箱与 LX 接口请求（Node 子进程通信、自动转换定时任务）：xiaomusic/js_plugin_manager.py
• 全部在线搜索 REST 接口（/api/js-plugins/*、/api/lxServer/*、/api/advanced-config/*、/api/password/*）：xiaomusic/api/routers/plugin.py
• 后台配置页及脚本：setting.html、setting-lxserver.js、setting-musicfree.js、setting-backend.js
• 网页搜索页：xiaomusic/static/onlineSearch/index.html
• 配置文件模板：xiaomusic/plugins-config-example.json
• 历史问题记录：docs/issues/

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