miao-moe/Koneko_api_for_QZ-Music
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: reset version to v0.0.1

Browse Source
This commit is contained in:
miao-moe
2026-06-20 12:48:28 +08:00
parent cf5d093f0b
commit 42ff3bde8e
16 changed files with 1687 additions and 2017 deletions
Download Patch File Download Diff File Expand all files Collapse all files

620
QZ_Music-V2 插件规范(v1.0.3).md
View File

@@ -1,137 +1,122 @@
# 插件开发帮助文档
> **版本**: v1.0.3
# 鎻掍欢寮€鍙戝府鍔╂枃妗?
> **鐗堟湰**: v1.0.3
>
> 撰写人: 蜻蜓的好朋友 : Miao-moe
> 鎾板啓浜? 铚昏湏鐨勫ソ鏈嬪弸 : Miao-moe
> GitHub: [Miao-moe](https://github.com/Miao-moe)
## 目录
1. [概述](#概述)
2. [核心设计原则](#核心设计原则)
3. [从其他平台迁移指南](#从其他平台迁移指南)
4. [插件基本结构](#插件基本结构)
5. [数据格式规范](#数据格式规范)
6. [示例代码详解](#示例代码详解)
7. [平台配置参考](#平台配置参考)
8. [开发建议](#开发建议)
9. [常见问题](#常见问题)
## 鐩綍
1. [姒傝堪](#姒傝堪)
2. [鏍稿績璁捐鍘熷垯](#鏍稿績璁捐鍘熷垯)
3. [浠庡叾浠栧钩鍙拌縼绉绘寚鍗梋(#浠庡叾浠栧钩鍙拌縼绉绘寚鍗?
4. [鎻掍欢鍩烘湰缁撴瀯](#鎻掍欢鍩烘湰缁撴瀯)
5. [鏁版嵁鏍煎紡瑙勮寖](#鏁版嵁鏍煎紡瑙勮寖)
6. [绀轰緥浠ｇ爜璇﹁В](#绀轰緥浠ｇ爜璇﹁В)
7. [骞冲彴閰嶇疆鍙傝€僝(#骞冲彴閰嶇疆鍙傝€?
8. [寮€鍙戝缓璁甝(#寮€鍙戝缓璁?
9. [甯歌闂](#甯歌闂)
---
## 概述
## 姒傝堪
本文档用于指导开发者编写音源插件。本系统使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 `module.exports` 导出功能接口。
鏈枃妗ｇ敤浜庢寚瀵煎紑鍙戣€呯紪鍐欓煶婧愭彃浠躲€傛湰绯荤粺浣跨敤 Node.js 杩愯鏃剁幆澧冿紝鎻掍欢閲囩敤 CommonJS 妯″潡瑙勮寖锛岄€氳繃 `module.exports` 瀵煎嚭鍔熻兘鎺ュ彛銆?
### 涓庡叾浠栫郴缁熺殑鍖哄埆
### 与其他系统的区别
| 特性 | 本系统 | 其他系统 |
| 鐗规€?| 鏈郴缁?| 鍏朵粬绯荤粺 |
|------|--------|----------|
| 运行时 | Node.js | JavaScript 运行时 |
| 模块规范 | CommonJS | 全局事件监听 |
| 导出方式 | `module.exports` | 事件发送 |
| 通信方式 | 直接函数调用 | 事件驱动 |
| HTTP 请求 | `axios` 或内置 `httpFetch` | 全局请求对象 |
| 杩愯鏃?| Node.js | JavaScript 杩愯鏃?|
| 妯″潡瑙勮寖 | CommonJS | 鍏ㄥ眬浜嬩欢鐩戝惉 |
| 瀵煎嚭鏂瑰紡 | `module.exports` | 浜嬩欢鍙戦€?|
| 閫氫俊鏂瑰紡 | 鐩存帴鍑芥暟璋冪敤 | 浜嬩欢椹卞姩 |
| HTTP 璇锋眰 | `axios` 鎴栧唴缃?`httpFetch` | 鍏ㄥ眬璇锋眰瀵硅薄 |
### 插件类型
本系统插件属于**完整音源插件**，核心功能包括：
- 搜索内容
- 获取播放 URL
- 获取歌词
- 获取列表/合集信息
- 获取热搜/排行榜
### 鎻掍欢绫诲瀷
鏈郴缁熸彃浠跺睘浜?*瀹屾暣闊虫簮鎻掍欢**锛屾牳蹇冨姛鑳藉寘鎷細
- 鎼滅储鍐呭
- 鑾峰彇鎾斁 URL
- 鑾峰彇姝岃瘝
- 鑾峰彇鍒楄〃/鍚堥泦淇℃伅
- 鑾峰彇鐑悳/鎺掕姒?
---
## 核心设计原则
## 鏍稿績璁捐鍘熷垯
### 1. 单平台原则（重要）
**每个插件只支持一个平台**，例如：
- ✅ 平台A插件（仅支持 A）
- ✅ 平台B插件（仅支持 B）
- ❌ 聚合插件（同时支持 A + B + C）
**原因说明**：
```
用户向插件传配置只能通过环境变量（env）
如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
单平台插件更清晰，维护成本低，不易出现"代码屎山"
### 1. 鍗曞钩鍙板師鍒欙紙閲嶈锛?
**姣忎釜鎻掍欢鍙敮鎸佷竴涓钩鍙?*锛屼緥濡傦細
- 鉁?骞冲彴A鎻掍欢锛堜粎鏀寔 A锛?- 鉁?骞冲彴B鎻掍欢锛堜粎鏀寔 B锛?- 鉂?鑱氬悎鎻掍欢锛堝悓鏃舵敮鎸?A + B + C锛?
**鍘熷洜璇存槑**锛?```
鐢ㄦ埛鍚戞彃浠朵紶閰嶇疆鍙兘閫氳繃鐜鍙橀噺锛坋nv锛?濡傛灉鎻掍欢鏀寔澶氬钩鍙帮紝鍒囨崲骞冲彴鏃堕渶瑕佷慨鏀圭幆澧冨彉閲忥紝鎿嶄綔绻佺悙
鍗曞钩鍙版彃浠舵洿娓呮櫚锛岀淮鎶ゆ垚鏈綆锛屼笉鏄撳嚭鐜?浠ｇ爜灞庡北"
```
**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。
**濡傞渶澶氬钩鍙版敮鎸?*锛氬缓璁嚜寤哄悗绔湇鍔★紝缁熶竴澶勭悊鎼滅储鍜?URL 鑾峰彇锛屽墠绔彃浠跺彧浣滀负浠ｇ悊銆?
### 2. 閰嶇疆鏂瑰紡
### 2. 配置方式
通过 `global.env` 读取环境变量（JSON 格式）：
閫氳繃 `global.env` 璇诲彇鐜鍙橀噺锛圝SON 鏍煎紡锛夛細
```javascript
// 读取用户配置的 API 密钥
// 璇诲彇鐢ㄦ埛閰嶇疆鐨?API 瀵嗛挜
const env = global.env || {}
const API_KEY = env.API_KEY || ''
// 读取自定义服务端地址
const CUSTOM_SERVER = env.SERVER_URL || '默认地址'
// 璇诲彇鑷畾涔夋湇鍔＄鍦板潃
const CUSTOM_SERVER = env.SERVER_URL || '榛樿鍦板潃'
```
**环境变量加载方式**：
```javascript
**鐜鍙橀噺鍔犺浇鏂瑰紡**锛?```javascript
const plugin = require('./index.js')
global.env = $envCommand // 由系统注入，格式为 JSON
global.env = $envCommand // 鐢辩郴缁熸敞鍏ワ紝鏍煎紡涓?JSON
// 在插件代码中通过 global.env 读取
// 鍦ㄦ彃浠朵唬鐮佷腑閫氳繃 global.env 璇诲彇
const env = global.env || {}
const API_KEY = env.API_KEY || ''
```
### 3. 支持的音质标识
| 标识 | 说明 |
### 3. 鏀寔鐨勯煶璐ㄦ爣璇?
| 鏍囪瘑 | 璇存槑 |
|------|------|
| `128k` | 标准音质 |
| `320k` | 高品音质 |
| `flac` | 无损音质 |
| `flac24bit` | 高解析度无损 |
| `hires` | 超高解析度 |
| `128k` | 鏍囧噯闊宠川 |
| `320k` | 楂樺搧闊宠川 |
| `flac` | 鏃犳崯闊宠川 |
| `flac24bit` | 楂樿В鏋愬害鏃犳崯 |
| `hires` | 瓒呴珮瑙ｆ瀽搴?|
---
## 从其他平台迁移指南
### 迁移对照表
| 其他系统 | 本系统 | 说明 |
## 浠庡叾浠栧钩鍙拌縼绉绘寚鍗?
### 杩佺Щ瀵圭収琛?
| 鍏朵粬绯荤粺 | 鏈郴缁?| 璇存槑 |
|----------|--------|------|
| `globalThis.lx` | `require` 模块 | 不再需要全局对象 |
| `globalThis.lx.request` | `axios` 或 `httpFetch` | 使用标准 HTTP 库 |
| `globalThis.lx.env` | `global.env` | 环境变量读取方式 |
| `on(EVENT_NAMES.request, ...)` | 直接导出函数 | 改为函数导出 |
| `send(EVENT_NAMES.inited, ...)` | `module.exports` | 改为模块导出 |
| `musicInfo.songmid` | `musicInfo.id` | 字段名可能不同 |
| `info.type` | `quality` 参数 | 音质参数位置 |
| `globalThis.lx` | `require` 妯″潡 | 涓嶅啀闇€瑕佸叏灞€瀵硅薄 |
| `globalThis.lx.request` | `axios` 鎴?`httpFetch` | 浣跨敤鏍囧噯 HTTP 搴?|
| `globalThis.lx.env` | `global.env` | 鐜鍙橀噺璇诲彇鏂瑰紡 |
| `on(EVENT_NAMES.request, ...)` | 鐩存帴瀵煎嚭鍑芥暟 | 鏀逛负鍑芥暟瀵煎嚭 |
| `send(EVENT_NAMES.inited, ...)` | `module.exports` | 鏀逛负妯″潡瀵煎嚭 |
| `musicInfo.songmid` | `musicInfo.id` | 瀛楁鍚嶅彲鑳戒笉鍚?|
| `info.type` | `quality` 鍙傛暟 | 闊宠川鍙傛暟浣嶇疆 |
### 迁移步骤
### 杩佺Щ姝ラ
#### 步骤 1：修改模块导入
**其他系统原代码：**
#### 姝ラ 1锛氫慨鏀规ā鍧楀鍏?
**鍏朵粬绯荤粺鍘熶唬鐮侊細**
```javascript
const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
```
**本系统新代码：**
**鏈郴缁熸柊浠ｇ爜锛?*
```javascript
const axios = require('axios')
const crypto = require('crypto')
// 环境变量从 global.env 读取
// 鐜鍙橀噺浠?global.env 璇诲彇
const env = global.env || {}
const API_KEY = env.API_KEY || ''
```
#### 步骤 2：修改 HTTP 请求
#### 姝ラ 2锛氫慨鏀?HTTP 璇锋眰
**其他系统原代码：**
**鍏朵粬绯荤粺鍘熶唬鐮侊細**
```javascript
function httpRequest(url) {
return new Promise((resolve, reject) => {
@@ -143,7 +128,7 @@ function httpRequest(url) {
}
```
**本系统新代码：**
**鏈郴缁熸柊浠ｇ爜锛?*
```javascript
async function httpRequest(url, options = {}) {
const response = await axios({
@@ -156,11 +141,10 @@ async function httpRequest(url, options = {}) {
}
```
#### 步骤 3：修改函数导出
**其他系统原代码：**
#### 姝ラ 3锛氫慨鏀瑰嚱鏁板鍑?
**鍏朵粬绯荤粺鍘熶唬鐮侊細**
```javascript
// 事件监听方式
// 浜嬩欢鐩戝惉鏂瑰紡
on(EVENT_NAMES.request, ({ action, source, info }) => {
switch (action) {
case 'musicUrl':
@@ -168,72 +152,68 @@ on(EVENT_NAMES.request, ({ action, source, info }) => {
}
})
// 初始化事件
send(EVENT_NAMES.inited, {
// 鍒濆鍖栦簨浠?send(EVENT_NAMES.inited, {
status: true,
sources: musicSource
})
```
**本系统新代码：**
**鏈郴缁熸柊浠ｇ爜锛?*
```javascript
// 直接导出函数
// 鐩存帴瀵煎嚭鍑芥暟
module.exports = {
// 搜索功能
// 鎼滅储鍔熻兘
musicSearch,
// 获取 URL
// 鑾峰彇 URL
getUrl,
// 获取歌词
// 鑾峰彇姝岃瘝
getLyric,
// 获取列表
// 鑾峰彇鍒楄〃
songList,
// 获取合集
// 鑾峰彇鍚堥泦
album,
// 获取热搜
// 鑾峰彇鐑悳
hotSearch,
// 插件信息
// 鎻掍欢淇℃伅
pluginInfo: {
info: { id: 'A', name: '平台A', version: '3' },
info: { id: 'A', name: '骞冲彴A', version: '3' },
quality: [...],
supportFunc: [...]
}
}
```
#### 步骤 4：修改返回数据格式
**其他系统原代码：**
#### 姝ラ 4锛氫慨鏀硅繑鍥炴暟鎹牸寮?
**鍏朵粬绯荤粺鍘熶唬鐮侊細**
```javascript
// 直接返回 URL 字符串
return 'https://example.com/audio.mp3'
// 鐩存帴杩斿洖 URL 瀛楃涓?return 'https://example.com/audio.mp3'
// 或返回歌词对象（其他系统格式）
return {
lyric: '[00:00.000]歌词内容',
tlyric: '[00:00.000]翻译歌词'
// 鎴栬繑鍥炴瓕璇嶅璞★紙鍏朵粬绯荤粺鏍煎紡锛?return {
lyric: '[00:00.000]姝岃瘝鍐呭',
tlyric: '[00:00.000]缈昏瘧姝岃瘝'
}
```
**本系统新代码：**
**鏈郴缁熸柊浠ｇ爜锛?*
```javascript
// 搜索返回统一格式
// 鎼滅储杩斿洖缁熶竴鏍煎紡
return {
list: [{
id: '123456',
name: '内容名',
artists: '创作者',
name: '鍐呭鍚?,
artists: '鍒涗綔鑰?,
source: 'A',
pic: '封面URL',
mPic: '中封面URL',
sPic: '小封面URL',
albumName: '合集名',
albumId: '合集ID',
pic: '灏侀潰URL',
mPic: '涓皝闈RL',
sPic: '灏忓皝闈RL',
albumName: '鍚堥泦鍚?,
albumId: '鍚堥泦ID',
interval: '03:45',
qualities: { '128k': '4.2M', 'flac': '35M' }
}],
@@ -244,92 +224,79 @@ return {
source: 'A'
}
// 歌词返回格式（见下文歌词格式规范）
// 系统支持多种歌词格式，返回有的即可
return {
lrc: 'LRC格式歌词',
qrc: 'QRC逐字歌词',
krc: 'KRC歌词',
ttml: 'TTML歌词',
translate: '翻译歌词'
// 姝岃瘝杩斿洖鏍煎紡锛堣涓嬫枃姝岃瘝鏍煎紡瑙勮寖锛?// 绯荤粺鏀寔澶氱姝岃瘝鏍煎紡锛岃繑鍥炴湁鐨勫嵆鍙?return {
lrc: 'LRC鏍煎紡姝岃瘝',
qrc: 'QRC閫愬瓧姝岃瘝',
krc: 'KRC姝岃瘝',
ttml: 'TTML姝岃瘝',
translate: '缈昏瘧姝岃瘝'
}
// 或直接返回歌词文本字符串（系统会自动判断格式）
return '[00:00.000]歌词内容\n[00:05.000]第二行歌词...'
// 鎴栫洿鎺ヨ繑鍥炴瓕璇嶆枃鏈瓧绗︿覆锛堢郴缁熶細鑷姩鍒ゆ柇鏍煎紡锛?return '[00:00.000]姝岃瘝鍐呭\n[00:05.000]绗簩琛屾瓕璇?..'
```
---
## 插件基本结构
## 鎻掍欢鍩烘湰缁撴瀯
### 核心导入
### 鏍稿績瀵煎叆
```javascript
'use strict'
// 标准 Node.js 模块
// 鏍囧噯 Node.js 妯″潡
const axios = require('axios')
const crypto = require('crypto')
```
### 配置区域
### 閰嶇疆鍖哄煙
```javascript
// ========== 用户可配置区域 ==========
// ========== 鐢ㄦ埛鍙厤缃尯鍩?==========
// 从 global.env 读取环境变量（JSON 格式）
const env = global.env || {}
// 浠?global.env 璇诲彇鐜鍙橀噺锛圝SON 鏍煎紡锛?const env = global.env || {}
// 服务端地址（用户可通过环境变量覆盖）
const API_BASE = env.SERVER_URL || 'https://your-server.com'
// 鏈嶅姟绔湴鍧€锛堢敤鎴峰彲閫氳繃鐜鍙橀噺瑕嗙洊锛?const API_BASE = env.SERVER_URL || 'https://your-server.com'
// API 密钥（用户通过环境变量设置）
const API_KEY = env.API_KEY || ''
// API 瀵嗛挜锛堢敤鎴烽€氳繃鐜鍙橀噺璁剧疆锛?const API_KEY = env.API_KEY || ''
// 当前平台标识（单平台插件固定值）
// 褰撳墠骞冲彴鏍囪瘑锛堝崟骞冲彴鎻掍欢鍥哄畾鍊硷級
const PLATFORM = 'A'
// 支持的音质列表
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
// 鏀寔鐨勯煶璐ㄥ垪琛?const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
```
### 导出结构
### 瀵煎嚭缁撴瀯
```javascript
// ========== 插件导出 ==========
// ========== 鎻掍欢瀵煎嚭 ==========
module.exports = {
// 核心功能（必须实现）
musicSearch, // 内容搜索
getUrl, // 获取 URL
// 鏍稿績鍔熻兘锛堝繀椤诲疄鐜帮級
musicSearch, // 鍐呭鎼滅储
getUrl, // 鑾峰彇 URL
// 可选功能
getLyric, // 获取歌词
songList, // 列表详情
album, // 合集详情
hotSearch, // 热搜词
tipSearch, // 搜索提示
leaderboard, // 排行榜
// 插件信息（必须）
// 鍙€夊姛鑳? getLyric, // 鑾峰彇姝岃瘝
songList, // 鍒楄〃璇︽儏
album, // 鍚堥泦璇︽儏
hotSearch, // 鐑悳璇? tipSearch, // 鎼滅储鎻愮ず
leaderboard, // 鎺掕姒?
// 鎻掍欢淇℃伅锛堝繀椤伙級
pluginInfo: {
info: {
id: 'A', // 平台标识
name: '平台A', // 显示名称
description: '平台A插件', // 描述
version: '3' // 版本号
},
env: [ // 环境变量配置
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
id: 'A', // 骞冲彴鏍囪瘑
name: '骞冲彴A', // 鏄剧ず鍚嶇О
description: '骞冲彴A鎻掍欢', // 鎻忚堪
version: '3' // 鐗堟湰鍙? },
env: [ // 鐜鍙橀噺閰嶇疆
{ key: 'API_KEY', name: 'API瀵嗛挜', description: '鏈嶅姟绔疉PI瀵嗛挜' }
],
ext: [], // 扩展功能
quality: [ // 支持的音质
{ name: '标准音质', ui: '标', id: '128k' },
{ name: '高品音质', ui: 'HQ', id: '320k' },
{ name: '无损音质', ui: 'SQ', id: 'flac' }
ext: [], // 鎵╁睍鍔熻兘
quality: [ // 鏀寔鐨勯煶璐? { name: '鏍囧噯闊宠川', ui: '鏍?, id: '128k' },
{ name: '楂樺搧闊宠川', ui: 'HQ', id: '320k' },
{ name: '鏃犳崯闊宠川', ui: 'SQ', id: 'flac' }
],
supportFunc: [ // 支持的功能
'search_song',
supportFunc: [ // 鏀寔鐨勫姛鑳? 'search_song',
'search_playlist',
'playlist',
'album',
@@ -341,143 +308,124 @@ module.exports = {
---
## 数据格式规范
## 鏁版嵁鏍煎紡瑙勮寖
### 搜索结果统一格式
### 鎼滅储缁撴灉缁熶竴鏍煎紡
```javascript
{
list: [
{
id: String, // 唯一标识
name: String, // 名称
artists: String, // 创作者（用 "、" 分隔）
source: String, // 平台标识
pic: String, // 大封面 URL
mPic: String, // 中封面 URL
sPic: String, // 小封面 URL
albumName: String, // 合集名
albumId: String, // 合集 ID
interval: String, // 时长 "mm:ss"
qualities: { // 音质 -> 文件大小
id: String, // 鍞竴鏍囪瘑
name: String, // 鍚嶇О
artists: String, // 鍒涗綔鑰咃紙鐢?"銆? 鍒嗛殧锛? source: String, // 骞冲彴鏍囪瘑
pic: String, // 澶у皝闈?URL
mPic: String, // 涓皝闈?URL
sPic: String, // 灏忓皝闈?URL
albumName: String, // 鍚堥泦鍚? albumId: String, // 鍚堥泦 ID
interval: String, // 鏃堕暱 "mm:ss"
qualities: { // 闊宠川 -> 鏂囦欢澶у皬
'128k': '4.2M',
'320k': '8.5M',
'flac': '35M'
}
}
],
total: Number, // 总数量
page: Number, // 当前页码
limit: Number, // 每页数量
allPage: Number, // 总页数
source: String // 平台标识
total: Number, // 鎬绘暟閲? page: Number, // 褰撳墠椤电爜
limit: Number, // 姣忛〉鏁伴噺
allPage: Number, // 鎬婚〉鏁? source: String // 骞冲彴鏍囪瘑
}
```
### 歌词返回格式
**重要说明**：系统会自动判断歌词格式（lrc、qrc、krc、ttml 等），插件只需返回对应的歌词字段即可。
### 姝岃瘝杩斿洖鏍煎紡
**閲嶈璇存槑**锛氱郴缁熶細鑷姩鍒ゆ柇姝岃瘝鏍煎紡锛坙rc銆乹rc銆乲rc銆乼tml 绛夛級锛屾彃浠跺彧闇€杩斿洖瀵瑰簲鐨勬瓕璇嶅瓧娈靛嵆鍙€?
```javascript
// 推荐返回格式
// 鎺ㄨ崘杩斿洖鏍煎紡
{
lrc: String, // LRC 格式歌词
qrc: String, // QRC 逐字歌词
krc: String, // KRC 歌词
ttml: String, // TTML 歌词
translate: String // 翻译歌词
lrc: String, // LRC 鏍煎紡姝岃瘝
qrc: String, // QRC 閫愬瓧姝岃瘝
krc: String, // KRC 姝岃瘝
ttml: String, // TTML 姝岃瘝
translate: String // 缈昏瘧姝岃瘝
}
// 或者直接返回歌词文本字符串（系统会自动判断格式）
return '[00:00.000]歌词内容\n[00:05.000]第二行歌词...'
// 鎴栬€呯洿鎺ヨ繑鍥炴瓕璇嶆枃鏈瓧绗︿覆锛堢郴缁熶細鑷姩鍒ゆ柇鏍煎紡锛?return '[00:00.000]姝岃瘝鍐呭\n[00:05.000]绗簩琛屾瓕璇?..'
```
**字段说明**：
| 字段 | 说明 | 格式 |
**瀛楁璇存槑**锛?
| 瀛楁 | 璇存槑 | 鏍煎紡 |
|------|------|------|
| `lrc` | 标准 LRC 歌词 | `[mm:ss.ms]歌词内容` |
| `qrc` | 逐字歌词 | QRC 格式（Base64 编码） |
| `krc` | KRC 歌词 | KRC 格式 |
| `ttml` | TTML 歌词 | TTML/XML 格式 |
| `translate` | 翻译歌词 | LRC 格式或纯文本 |
| `lrc` | 鏍囧噯 LRC 姝岃瘝 | `[mm:ss.ms]姝岃瘝鍐呭` |
| `qrc` | 閫愬瓧姝岃瘝 | QRC 鏍煎紡锛圔ase64 缂栫爜锛?|
| `krc` | KRC 姝岃瘝 | KRC 鏍煎紡 |
| `ttml` | TTML 姝岃瘝 | TTML/XML 鏍煎紡 |
| `translate` | 缈昏瘧姝岃瘝 | LRC 鏍煎紡鎴栫函鏂囨湰 |
**注意事项**：
- 以上字段均为可选，返回有的即可
- 系统会自动识别歌词格式
- `translate` 用于翻译歌词
- 直接返回歌词文本字符串也是允许的，系统会尝试自动判断其格式
- 不同平台可能返回不同格式，如：平台A可能返回 `qrc` + `translate`，平台B可能返回 `lrc` + `tlyric`
**娉ㄦ剰浜嬮」**锛?- 浠ヤ笂瀛楁鍧囦负鍙€夛紝杩斿洖鏈夌殑鍗冲彲
- 绯荤粺浼氳嚜鍔ㄨ瘑鍒瓕璇嶆牸寮?- `translate` 鐢ㄤ簬缈昏瘧姝岃瘝
- 鐩存帴杩斿洖姝岃瘝鏂囨湰瀛楃涓蹭篃鏄厑璁哥殑锛岀郴缁熶細灏濊瘯鑷姩鍒ゆ柇鍏舵牸寮?- 涓嶅悓骞冲彴鍙兘杩斿洖涓嶅悓鏍煎紡锛屽锛氬钩鍙癆鍙兘杩斿洖 `qrc` + `translate`锛屽钩鍙癇鍙兘杩斿洖 `lrc` + `tlyric`
### 列表详情统一格式
### 鍒楄〃璇︽儏缁熶竴鏍煎紡
```javascript
{
list: [/* 内容列表，格式同搜索结果 */],
list: [/* 鍐呭鍒楄〃锛屾牸寮忓悓鎼滅储缁撴灉 */],
page: Number,
limit: Number,
total: Number,
source: String,
info: {
name: String, // 列表名
img: String, // 封面图
desc: String, // 描述
author: String // 创建者
}
name: String, // 鍒楄〃鍚? img: String, // 灏侀潰鍥? desc: String, // 鎻忚堪
author: String // 鍒涘缓鑰? }
}
```
### 合集详情统一格式
### 鍚堥泦璇︽儏缁熶竴鏍煎紡
```javascript
{
list: [/* 内容列表，格式同搜索结果 */],
list: [/* 鍐呭鍒楄〃锛屾牸寮忓悓鎼滅储缁撴灉 */],
page: Number,
limit: Number,
total: Number,
source: String,
info: {
name: String, // 合集名
img: String, // 封面图
desc: String, // 描述
author: String // 创作者
}
name: String, // 鍚堥泦鍚? img: String, // 灏侀潰鍥? desc: String, // 鎻忚堪
author: String // 鍒涗綔鑰? }
}
```
---
## 示例代码详解
## 绀轰緥浠ｇ爜璇﹁В
### 完整插件模板
### 瀹屾暣鎻掍欢妯℃澘
```javascript
'use strict'
// ==================== 核心导入 ====================
// ==================== 鏍稿績瀵煎叆 ====================
const axios = require('axios')
const crypto = require('crypto')
// ==================== 配置区域 ====================
// ==================== 閰嶇疆鍖哄煙 ====================
// 从 global.env 读取环境变量（JSON 格式）
const env = global.env || {}
// 浠?global.env 璇诲彇鐜鍙橀噺锛圝SON 鏍煎紡锛?const env = global.env || {}
// 平台标识（固定值，单平台插件）
// 骞冲彴鏍囪瘑锛堝浐瀹氬€硷紝鍗曞钩鍙版彃浠讹級
const PLATFORM = 'A'
// 服务端配置
const CONFIG = {
// 鏈嶅姟绔厤缃?const CONFIG = {
serverUrl: env.SERVER_URL || 'https://api.example.com',
apiKey: env.API_KEY || '',
timeout: 10000
}
// 支持的音质
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
// 鏀寔鐨勯煶璐?const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
// ==================== 工具函数 ====================
// ==================== 宸ュ叿鍑芥暟 ====================
function sizeFormate(size) {
if (!size || isNaN(size)) return ''
@@ -496,7 +444,7 @@ function formatPlayTime(time) {
function formatArtistName(artistList) {
if (!artistList || !Array.isArray(artistList)) return ''
return artistList.map(a => a.name || a).join('、')
return artistList.map(a => a.name || a).join('銆?)
}
function decodeName(str) {
@@ -510,7 +458,7 @@ function decodeName(str) {
.replace(/ /g, ' ')
}
// ==================== 核心功能 ====================
// ==================== 鏍稿績鍔熻兘 ====================
async function musicSearch(str, page = 1, limit = 20) {
const params = { keyword: str, page, limit }
@@ -567,7 +515,7 @@ async function getUrl(id, quality) {
const data = response.data
if (!data.url || !data.url.startsWith('http')) {
throw new Error('获取链接失败')
throw new Error('鑾峰彇閾炬帴澶辫触')
}
return data.url
@@ -583,9 +531,8 @@ async function getLyric(id) {
const data = response.data
// 返回歌词对象，系统会自动判断格式
// 返回有的字段即可，不需要全部字段
return {
// 杩斿洖姝岃瘝瀵硅薄锛岀郴缁熶細鑷姩鍒ゆ柇鏍煎紡
// 杩斿洖鏈夌殑瀛楁鍗冲彲锛屼笉闇€瑕佸叏閮ㄥ瓧娈? return {
lrc: data.lrc || '',
qrc: data.qrc || '',
krc: data.krc || '',
@@ -593,8 +540,7 @@ async function getLyric(id) {
translate: data.translate || ''
}
// 或者直接返回歌词文本
// return data.lyric
// 鎴栬€呯洿鎺ヨ繑鍥炴瓕璇嶆枃鏈? // return data.lyric
}
async function songList(id, page = 1, limit = 20) {
@@ -688,7 +634,7 @@ async function hotSearch() {
}
}
// ==================== 插件导出 ====================
// ==================== 鎻掍欢瀵煎嚭 ====================
module.exports = {
musicSearch,
@@ -701,19 +647,19 @@ module.exports = {
pluginInfo: {
info: {
id: PLATFORM,
name: '平台A',
description: '平台A插件',
name: '骞冲彴A',
description: '骞冲彴A鎻掍欢',
version: '3'
},
env: [
{ key: 'SERVER_URL', name: '服务端地址', description: '自定义服务端地址' },
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
{ key: 'SERVER_URL', name: '鏈嶅姟绔湴鍧€', description: '鑷畾涔夋湇鍔＄鍦板潃' },
{ key: 'API_KEY', name: 'API瀵嗛挜', description: '鏈嶅姟绔疉PI瀵嗛挜' }
],
ext: [],
quality: [
{ name: '标准音质', ui: '标', id: '128k' },
{ name: '高品音质', ui: 'HQ', id: '320k' },
{ name: '无损音质', ui: 'SQ', id: 'flac' }
{ name: '鏍囧噯闊宠川', ui: '鏍?, id: '128k' },
{ name: '楂樺搧闊宠川', ui: 'HQ', id: '320k' },
{ name: '鏃犳崯闊宠川', ui: 'SQ', id: 'flac' }
],
supportFunc: ['search_song', 'search_playlist', 'playlist', 'album', 'lyric']
}
@@ -722,21 +668,19 @@ module.exports = {
---
## 平台配置参考
## 骞冲彴閰嶇疆鍙傝€?
### 鍚勫钩鍙版爣璇嗗鐓ц〃
### 各平台标识对照表
| 平台 | 标识 | 常见 ID 字段 |
| 骞冲彴 | 鏍囪瘑 | 甯歌 ID 瀛楁 |
|------|------|-------------|
| 平台A | `A` | `id` |
| 平台B | `B` | `id` |
| 平台C | `C` | `id`, `hash` |
| 平台D | `D` | `hash`, `id` |
| 平台E | `E` | `id` |
| 平台F | `F` | `id` |
### 音质支持参考
| 骞冲彴A | `A` | `id` |
| 骞冲彴B | `B` | `id` |
| 骞冲彴C | `C` | `id`, `hash` |
| 骞冲彴D | `D` | `hash`, `id` |
| 骞冲彴E | `E` | `id` |
| 骞冲彴F | `F` | `id` |
### 闊宠川鏀寔鍙傝€?
```javascript
const PLATFORM_QUALITIES = {
A: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
@@ -750,113 +694,95 @@ const PLATFORM_QUALITIES = {
---
## 开发建议
### 多文件开发
**推荐使用多文件开发模式**，将不同功能模块分离，防止代码堆叠：
## 寮€鍙戝缓璁?
### 澶氭枃浠跺紑鍙?
**鎺ㄨ崘浣跨敤澶氭枃浠跺紑鍙戞ā寮?*锛屽皢涓嶅悓鍔熻兘妯″潡鍒嗙锛岄槻姝唬鐮佸爢鍙狅細
```
plugin/
├── index.js # 主入口，导出模块
├── search.js # 搜索相关功能
├── lyric.js # 歌词相关功能
├── playlist.js # 列表相关功能
├── utils.js # 工具函数
└── config.js # 配置常量
鈹溾攢鈹€ index.js # 涓诲叆鍙ｏ紝瀵煎嚭妯″潡
鈹溾攢鈹€ search.js # 鎼滅储鐩稿叧鍔熻兘
鈹溾攢鈹€ lyric.js # 姝岃瘝鐩稿叧鍔熻兘
鈹溾攢鈹€ playlist.js # 鍒楄〃鐩稿叧鍔熻兘
鈹溾攢鈹€ utils.js # 宸ュ叿鍑芥暟
鈹斺攢鈹€ config.js # 閰嶇疆甯搁噺
```
### 使用 ncc 打包
开发完成后，使用 `ncc` 将多文件打包为单文件即可：
### 浣跨敤 ncc 鎵撳寘
寮€鍙戝畬鎴愬悗锛屼娇鐢?`ncc` 灏嗗鏂囦欢鎵撳寘涓哄崟鏂囦欢鍗冲彲锛?
```bash
# 安装 ncc
# 瀹夎 ncc
npm install -g @vercel/ncc
# 打包
# 鎵撳寘
ncc build index.js -o dist
# 输出的 dist/index.js 即为最终插件文件
```
**ncc 打包优点**：
- 将多文件合并为单文件，便于分发
- 自动处理依赖关系
- 保持 CommonJS 兼容性
# 杈撳嚭鐨?dist/index.js 鍗充负鏈€缁堟彃浠舵枃浠?```
**ncc 鎵撳寘浼樼偣**锛?- 灏嗗鏂囦欢鍚堝苟涓哄崟鏂囦欢锛屼究浜庡垎鍙?- 鑷姩澶勭悊渚濊禆鍏崇郴
- 淇濇寔 CommonJS 鍏煎鎬?
---
## 常见问题
## 甯歌闂
### Q1: 如何从其他系统迁移到本系统？
### Q1: 濡備綍浠庡叾浠栫郴缁熻縼绉诲埌鏈郴缁燂紵
**A**: 参考本文档的"从其他平台迁移指南"章节，主要修改点：
1. 将 `globalThis.lx.request` 改为 `axios`
2. 将事件监听改为函数导出
3. 修改数据返回格式
4. 添加 `module.exports` 导出
5. 环境变量从 `global.env` 读取
**A**: 鍙傝€冩湰鏂囨。鐨?浠庡叾浠栧钩鍙拌縼绉绘寚鍗?绔犺妭锛屼富瑕佷慨鏀圭偣锛?1. 灏?`globalThis.lx.request` 鏀逛负 `axios`
2. 灏嗕簨浠剁洃鍚敼涓哄嚱鏁板鍑?3. 淇敼鏁版嵁杩斿洖鏍煎紡
4. 娣诲姞 `module.exports` 瀵煎嚭
5. 鐜鍙橀噺浠?`global.env` 璇诲彇
### Q2: 插件加载失败怎么办？
### Q2: 鎻掍欢鍔犺浇澶辫触鎬庝箞鍔烇紵
**A**: 检查以下几点：
1. 文件语法是否正确：`node -c your-plugin.js`
2. `pluginInfo` 是否完整
3. 导出的函数名是否正确
4. 依赖模块是否已安装（如 `axios`）
**A**: 妫€鏌ヤ互涓嬪嚑鐐癸細
1. 鏂囦欢璇硶鏄惁姝ｇ‘锛歚node -c your-plugin.js`
2. `pluginInfo` 鏄惁瀹屾暣
3. 瀵煎嚭鐨勫嚱鏁板悕鏄惁姝ｇ‘
4. 渚濊禆妯″潡鏄惁宸插畨瑁咃紙濡?`axios`锛?
### Q3: 鎼滅储杩斿洖绌虹粨鏋滐紵
### Q3: 搜索返回空结果？
**A**: 检查：
1. API 请求是否成功（查看日志）
2. 响应数据解析是否正确
3. 数据格式是否符合规范
4. 返回的 `source` 是否与平台标识一致
### Q4: 播放失败？
**A**: 检查：
1. `getUrl` 返回的 URL 是否有效
2. URL 是否以 `http` 开头
3. 音质标识是否正确
4. 是否有跨域或权限问题
### Q5: 用户如何配置插件？
**A**: 用户通过设置界面配置环境变量：
**A**: 妫€鏌ワ細
1. API 璇锋眰鏄惁鎴愬姛锛堟煡鐪嬫棩蹇楋級
2. 鍝嶅簲鏁版嵁瑙ｆ瀽鏄惁姝ｇ‘
3. 鏁版嵁鏍煎紡鏄惁绗﹀悎瑙勮寖
4. 杩斿洖鐨?`source` 鏄惁涓庡钩鍙版爣璇嗕竴鑷?
### Q4: 鎾斁澶辫触锛?
**A**: 妫€鏌ワ細
1. `getUrl` 杩斿洖鐨?URL 鏄惁鏈夋晥
2. URL 鏄惁浠?`http` 寮€澶?3. 闊宠川鏍囪瘑鏄惁姝ｇ‘
4. 鏄惁鏈夎法鍩熸垨鏉冮檺闂
### Q5: 鐢ㄦ埛濡備綍閰嶇疆鎻掍欢锛?
**A**: 鐢ㄦ埛閫氳繃璁剧疆鐣岄潰閰嶇疆鐜鍙橀噺锛?
```
SERVER_URL = 自定义服务端地址
API_KEY = 用户的API密钥
SERVER_URL = 鑷畾涔夋湇鍔＄鍦板潃
API_KEY = 鐢ㄦ埛鐨凙PI瀵嗛挜
```
插件通过 `global.env` 读取：
鎻掍欢閫氳繃 `global.env` 璇诲彇锛?
```javascript
const env = global.env || {}
const SERVER_URL = env.SERVER_URL || '默认地址'
const SERVER_URL = env.SERVER_URL || '榛樿鍦板潃'
```
### Q6: 歌词格式应该返回什么？
### Q6: 姝岃瘝鏍煎紡搴旇杩斿洖浠€涔堬紵
**A**: 返回包含 `lrc`、`qrc`、`krc`、`ttml`、`translate` 等字段的对象，或直接返回歌词文本字符串。系统会自动判断歌词格式。
**A**: 杩斿洖鍖呭惈 `lrc`銆乣qrc`銆乣krc`銆乣ttml`銆乣translate` 绛夊瓧娈电殑瀵硅薄锛屾垨鐩存帴杩斿洖姝岃瘝鏂囨湰瀛楃涓层€傜郴缁熶細鑷姩鍒ゆ柇姝岃瘝鏍煎紡銆?
---
## 闄勫綍
### 鍙傝€冭祫婧?
- Node.js 瀹樻柟鏂囨。
- axios 鏂囨。
- @vercel/ncc 鎵撳寘宸ュ叿
### 鐗堟湰鍘嗗彶
- v1.0.3: 褰撳墠鐗堟湰
- v1.0.0: 鍒濆鐗堟湰
---
## 附录
### 参考资源
- Node.js 官方文档
- axios 文档
- @vercel/ncc 打包工具
### 版本历史
- v1.0.3: 当前版本
- v1.0.0: 初始版本
---
**文档结束**
**鏂囨。缁撴潫**