准备工作：找到你的音乐 API 接口
云乐插件本身仅提供默认音乐数据，不做更新维护，如失效后你需要自行寻找（或搭建）一个能返回歌曲信息的 HTTP API 接口。常见来源为第三方音乐接口，请自行寻找。
在开始配置之前，你需要先确认两件事：
-
找到接口地址，例如
https://api.example.com/music/search?msg= - 了解接口返回的 JSON 数据结构
💡 注意：歌曲名称参数 msg= 必须放在接口链接的最末尾，其他参数（如音质、格式、数量等）放在前面。
例如：https://api.example.com/music/bdyy?type=json&sc=20&msg= ← 正确 ✅
例如：https://api.example.com/music/bdyy?msg=&type=json ← 错误 ❌
认识配置界面（总览）
下图是云乐插件的核心配置页，所有字段映射都在这里完成：
▲ 云乐插件配置界面（字段映射表）
单曲点歌区域
配置点播单首歌曲时，从 API 返回数据中提取歌名、歌手、封面、播放链接的字段路径。
列表点歌区域
配置搜索返回列表时，从 JSON 数组中提取每首歌曲信息的字段路径。
状态验证区域
配置判断 API 请求是否成功的状态字段和期望值。
序号参数
指定获取第几条数据的参数名称（索引）。
查看 API 返回的 JSON 数据
填写配置前，必须搞清楚你的 API 返回了什么样的数据结构。用浏览器打开接口地址，找到网络请求的响应内容。
A 列表接口的返回数据
"code": 200,
"text": "获取成功",
"data": [
{
"name": "十年",
"artist": "陈奕迅",
"_singer": [
"陈奕迅"
],
"detail_page": "https://www.kuwo.cn/play_detail/80403",
"pic": "https://img4.kuwo.cn/star/albumcover/300/s4s86/18/1347897214.jpg"
},
{
"name": "盗墓笔记·十年人间",
"artist": "李常超（Lao乾妈）",
"_singer": [
"李常超（Lao乾妈）"
],
"detail_page": "https://www.kuwo.cn/play_detail/64955890",
"pic": "https://img4.kuwo.cn/star/albumcover/300/s4s42/65/2863229906.jpg"
},
{
"name": "十年",
"artist": "陈奕迅",
"_singer": [
"陈奕迅"
],
"detail_page": "https://www.kuwo.cn/play_detail/24610258",
"pic": "https://img4.kuwo.cn/star/albumcover/300/s4s57/5/3594322917.jpg"
}
]
}
▲ 搜索"十年"时，API 返回的歌曲列表 JSON 数据（代码格式，可直接复制）
B 单曲接口的返回数据
"code": 200,
"data": {
"name": "十年",
"artist": "陈奕迅",
"cover": "https://img4.kuwo.cn/star/albumcover/120/s4s86/18/1347897214.jpg",
"detail_page": "https://www.kuwo.cn/play_detail/80403",
"play_url": "http://car-er.kuwo.cn/63d2443cccbb309459cde0493e84ed0d/6a72dcec/resource/30106/trackmedia/M500001OyHbk2MSIi4.mp3?from=bodian"
}
}
▲ 点播单首歌曲时，API 返回的 JSON 数据（代码格式，可直接复制）
列表接口和单曲接口都使用 data 作为上级字段。区别在于：列表接口中 上级字段 需要单独填写上级字段中，而单曲接口中 上级字段 需要直接填写在各个字段中。
状态字段 与 状态码
这两个字段用于验证 API 请求是否成功。它们对应的是单曲点播时返回数据中的状态信息。
"code": 200, ← 状态字段: code，状态码: 200
"data": {
"name": "十年",
"artist": "陈奕迅",
"cover": "https://...",
"play_url": "http://...mp3"
}
}
code
API 返回 JSON 中表示请求状态的字段名称
"code": 200, ← 这就是"状态字段"
"data": { ... }
}
200
状态字段的期望值，表示请求成功
"code": 200, ← "200"就是状态码
"data": { ... }
}
code，有些用 status，有些用 success。请根据你实际 API 返回的字段来填写，这里的 code 和 200 仅作示例。
列表点歌配置
列表点歌用于搜索返回多首歌曲的场景。它的配置和单曲点歌不同——需要指定歌曲数组所在的上级字段。
1 列表上级
"列表上级" 是指：在图3（列表接口返回数据）中，歌曲列表数组所在的父级字段名。
从图3可以看到，歌曲数组是 data 字段的值，所以此处填写 data。
有些接口可能用
result、list、songs 等作为数组字段名，也可能直接返回数组（没有上级字段），此时 留空 即可。
"code": 200,
"text": "获取成功",
// ↓ "data" 就是列表上级字段
"data": [
{
"name": "十年",
"artist": "陈奕迅",
"pic": "https://...jpg"
},
{
"name": "盗墓笔记·十年人间",
"artist": "李常超（Lao乾妈）",
"pic": "https://...jpg"
}
]
}
▲ 注释标注的位置就是 data 列表上级字段
2 列表歌名参数
name
列表中每首歌对象的歌曲名称对应的字段名。
// 在 data 数组中的每个对象：
"name": "十年" ← 歌名参数
}
3 列表歌手参数
artist
列表中每首歌对象的歌手名称对应的字段名。
// 在 data 数组中的每个对象：
"artist": "陈奕迅" ← 歌手参数
}
单曲点歌配置
单曲点歌的四个字段（歌名、歌手、封面、链接）中，data 也是上级字段。
它们与列表点歌的区别是：这里填写的是完整路径（含上级字段），而列表点歌是上级字段和子字段分开填。
1 歌名字段
data.name
完整路径 = 上级字段 data + . + 歌名在数据中的字段 name
"data": {
"name": "十年" ← data.name
}
}
如果单曲接口没有上级字段，只需填写
name；如果上级字段不是 data 而是 result，则填 result.name。
"code": 200,
"data": {
// ↓ 歌名字段: data.name
"name": "十年",
// ↓ 歌手字段: data.artist
"artist": "陈奕迅",
// ↓ 封面字段: data.cover
"cover": "https://img4.kuwo.cn/star/.../1347897214.jpg",
// ↓ 链接字段: data.play_url
"play_url": "http://car-er.kuwo.cn/.../M500001OyHbk2MSIi4.mp3"
}
}
2 歌手字段
data.artist
同样格式：上级字段 + 点 + 歌手字段名
3 封面字段
data.cover
注意：不同接口封面字段名可能不同，如 pic、img、album_pic
4 链接字段
data.play_url
播放地址字段。不同接口可能叫 url、src、mp3 等
★ 关键注意
data. 前缀，直接填字段名即可。✅ 列表和单曲如果都没有上级字段，列表上级和单曲字段中的上级都可以留空。
序号参数
n
序号参数用于指定获取第几条数据（索引/偏移量）。它对应 URL 中的一个查询参数，告诉接口"我要列表中的第几条"。
在下图示例接口中，n 就是这个参数名。
不同接口的参数名不同：大多数情况为
n，如果不是根据具体接口API文档的情况做调整。请务必查阅你的 API 文档确认正确的参数名，这里以 n 为例。
接口链接格式
这是最关键的一条规则：歌曲名称参数必须放在 URL 的最后面！（具体歌名参数要根据不同的接口文档进行调整，下面以msg为例）
正确格式
歌曲参数 msg= 在最末尾，其他参数（type、sc等）在前面。
错误格式
歌曲参数 msg= 不在末尾，插件无法正确拼接歌曲名称。
云乐插件会在接口链接末尾自动拼接用户输入的歌曲名称。例如用户点播"十年"：
如果 msg= 没有放在最后，拼接位置就会出错，导致请求失败。
完整配置对照表
基于图2-图4的示例数据，完整的填写参考如下：
| 配置项 | 填写值 | 数据来源 / 说明 |
|---|---|---|
| 歌名字段 | data.name |
图4单曲数据中的 data → name |
| 歌手字段 | data.artist |
图4单曲数据中的 data → artist |
| 封面字段 | data.cover |
图4单曲数据中的 data → cover（或 pic） |
| 链接字段 | data.play_url |
图4单曲数据中的 data → play_url |
| 序号参数 | n |
指定第几条数据（索引），查 API 文档确认参数名 |
| 列表上级 | data |
图3列表数据中数组的父级字段 |
| 列表歌名参数 | name |
图3列表每项中的歌名字段 |
| 列表歌手参数 | artist |
图3列表每项中的歌手字段 |
| 状态字段 | code |
图4返回 JSON 中的状态字段名 |
| 状态码 | 200 |
状态字段等于此值表示请求成功 |
⚠️ 以上值基于示例截图中的 API 结构。实际填写时请根据你的接口返回数据对应调整。
常见问题与自定义适配
如果 API 没有"data"这个上级字段怎么办？
两种情况：
-
✅
有上级字段但名称不同（如
result、response）：将单曲点歌字段中的data.xxx改为result.xxx，列表上级改为result。 -
✅
完全没有上级字段（JSON 根直接是歌曲信息）：列表上级留空，单曲点歌字段只写字段名（去掉
data.前缀）。
不同接口的字段名不一样怎么办？
对照下表，根据你的 API 实际返回的字段名来映射：
| 插件需要 | 可能的字段名 |
|---|---|
| 歌名 | name / title / songName / song |
| 歌手 | artist / singer / author / performer |
| 封面 | cover / pic / img / image / album_pic |
| 链接 | play_url / url / src / mp3 / music_url |
| 序号 | n / index / offset / id / page |
| 状态 | code / status / success / errno |
列表中每项的字段名和单曲的字段名不一致怎么办？
插件对列表点歌和单曲点歌使用不同的字段配置，所以两边的字段名可以不同，互不影响。
例如：你的列表接口用 title 表示歌名，单曲接口用 name，那么列表歌名参数填 title，歌名字段填 data.name 即可。
接口返回的 JSON 嵌套很深怎么办？（如 data.result.songs[0].info.name）
云乐插件通常支持用 . 分隔的路径，你可以写多层嵌套：
- 列表上级：
data.result - 列表歌名参数：
info.name（或songs.info.name，取决于层级） - 歌名字段：
data.result.info.name
如果嵌套太深插件不支持，建议找一个结构更扁平的音乐接口。
📋 配置流程总结
找接口
寻找可用的音乐 API，获取接口地址
看数据
F12 查看 JSON 返回结构，了解字段层级
对字段
按本文教程逐一映射每个配置项
调格式
检查上级字段和接口链接格式
测试
保存后点歌测试，确认配置正确
核心要点速记
- ① 接口自己找，云乐插件只是配置工具，不提供音乐数据源。
- ② 状态字段和状态码看单曲接口（图4）的返回值，不同接口的字段名和值可能不同。
-
③
列表上级 = 数组的父级字段名（图3中的
data），无上级则留空。 -
④
单曲点歌字段中的
data也是上级，路径写为data.xxx，无上级则只写xxx。 -
⑤
序号参数是第几条数据（索引），要查 API 文档，不同接口参数名不同（
n/index/offset等）。 - ⑥ 歌曲名称参数必须放在接口链接的最末尾！