863 lines
20 KiB
Markdown
863 lines
20 KiB
Markdown
# 插件开发帮助文档
|
||
|
||
> **版本**: v1.0.3
|
||
>
|
||
> 撰写人: 蜻蜓的好朋友 : Miao-moe
|
||
> GitHub: [Miao-moe](https://github.com/Miao-moe)
|
||
|
||
## 目录
|
||
1. [概述](#概述)
|
||
2. [核心设计原则](#核心设计原则)
|
||
3. [从其他平台迁移指南](#从其他平台迁移指南)
|
||
4. [插件基本结构](#插件基本结构)
|
||
5. [数据格式规范](#数据格式规范)
|
||
6. [示例代码详解](#示例代码详解)
|
||
7. [平台配置参考](#平台配置参考)
|
||
8. [开发建议](#开发建议)
|
||
9. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本文档用于指导开发者编写音源插件。本系统使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 `module.exports` 导出功能接口。
|
||
|
||
### 与其他系统的区别
|
||
|
||
| 特性 | 本系统 | 其他系统 |
|
||
|------|--------|----------|
|
||
| 运行时 | Node.js | JavaScript 运行时 |
|
||
| 模块规范 | CommonJS | 全局事件监听 |
|
||
| 导出方式 | `module.exports` | 事件发送 |
|
||
| 通信方式 | 直接函数调用 | 事件驱动 |
|
||
| HTTP 请求 | `axios` 或内置 `httpFetch` | 全局请求对象 |
|
||
|
||
### 插件类型
|
||
|
||
本系统插件属于**完整音源插件**，核心功能包括：
|
||
- 搜索内容
|
||
- 获取播放 URL
|
||
- 获取歌词
|
||
- 获取列表/合集信息
|
||
- 获取热搜/排行榜
|
||
|
||
---
|
||
|
||
## 核心设计原则
|
||
|
||
### 1. 单平台原则（重要）
|
||
|
||
**每个插件只支持一个平台**，例如：
|
||
- ✅ 平台A插件（仅支持 A）
|
||
- ✅ 平台B插件（仅支持 B）
|
||
- ❌ 聚合插件（同时支持 A + B + C）
|
||
|
||
**原因说明**：
|
||
```
|
||
用户向插件传配置只能通过环境变量（env）
|
||
如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
|
||
单平台插件更清晰，维护成本低，不易出现"代码屎山"
|
||
```
|
||
|
||
**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。
|
||
|
||
### 2. 配置方式
|
||
|
||
通过 `global.env` 读取环境变量（JSON 格式）：
|
||
|
||
```javascript
|
||
// 读取用户配置的 API 密钥
|
||
const env = global.env || {}
|
||
const API_KEY = env.API_KEY || ''
|
||
|
||
// 读取自定义服务端地址
|
||
const CUSTOM_SERVER = env.SERVER_URL || '默认地址'
|
||
```
|
||
|
||
**环境变量加载方式**：
|
||
```javascript
|
||
const plugin = require('./index.js')
|
||
global.env = $envCommand // 由系统注入，格式为 JSON
|
||
|
||
// 在插件代码中通过 global.env 读取
|
||
const env = global.env || {}
|
||
const API_KEY = env.API_KEY || ''
|
||
```
|
||
|
||
### 3. 支持的音质标识
|
||
|
||
| 标识 | 说明 |
|
||
|------|------|
|
||
| `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` 参数 | 音质参数位置 |
|
||
|
||
### 迁移步骤
|
||
|
||
#### 步骤 1：修改模块导入
|
||
|
||
**其他系统原代码：**
|
||
```javascript
|
||
const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
|
||
```
|
||
|
||
**本系统新代码：**
|
||
```javascript
|
||
const axios = require('axios')
|
||
const crypto = require('crypto')
|
||
|
||
// 环境变量从 global.env 读取
|
||
const env = global.env || {}
|
||
const API_KEY = env.API_KEY || ''
|
||
```
|
||
|
||
#### 步骤 2：修改 HTTP 请求
|
||
|
||
**其他系统原代码：**
|
||
```javascript
|
||
function httpRequest(url) {
|
||
return new Promise((resolve, reject) => {
|
||
request(url, { headers }, (err, resp) => {
|
||
if (err) return reject(err)
|
||
resolve(resp.body)
|
||
})
|
||
})
|
||
}
|
||
```
|
||
|
||
**本系统新代码：**
|
||
```javascript
|
||
async function httpRequest(url, options = {}) {
|
||
const response = await axios({
|
||
url,
|
||
method: options.method || 'GET',
|
||
headers: options.headers,
|
||
timeout: options.timeout || 10000
|
||
})
|
||
return response.data
|
||
}
|
||
```
|
||
|
||
#### 步骤 3：修改函数导出
|
||
|
||
**其他系统原代码：**
|
||
```javascript
|
||
// 事件监听方式
|
||
on(EVENT_NAMES.request, ({ action, source, info }) => {
|
||
switch (action) {
|
||
case 'musicUrl':
|
||
return getMusicUrl(info.musicInfo, info.type)
|
||
}
|
||
})
|
||
|
||
// 初始化事件
|
||
send(EVENT_NAMES.inited, {
|
||
status: true,
|
||
sources: musicSource
|
||
})
|
||
```
|
||
|
||
**本系统新代码：**
|
||
```javascript
|
||
// 直接导出函数
|
||
module.exports = {
|
||
// 搜索功能
|
||
musicSearch,
|
||
|
||
// 获取 URL
|
||
getUrl,
|
||
|
||
// 获取歌词
|
||
getLyric,
|
||
|
||
// 获取列表
|
||
songList,
|
||
|
||
// 获取合集
|
||
album,
|
||
|
||
// 获取热搜
|
||
hotSearch,
|
||
|
||
// 插件信息
|
||
pluginInfo: {
|
||
info: { id: 'A', name: '平台A', version: '3' },
|
||
quality: [...],
|
||
supportFunc: [...]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 步骤 4：修改返回数据格式
|
||
|
||
**其他系统原代码：**
|
||
```javascript
|
||
// 直接返回 URL 字符串
|
||
return 'https://example.com/audio.mp3'
|
||
|
||
// 或返回歌词对象（其他系统格式）
|
||
return {
|
||
lyric: '[00:00.000]歌词内容',
|
||
tlyric: '[00:00.000]翻译歌词'
|
||
}
|
||
```
|
||
|
||
**本系统新代码：**
|
||
```javascript
|
||
// 搜索返回统一格式
|
||
return {
|
||
list: [{
|
||
id: '123456',
|
||
name: '内容名',
|
||
artists: '创作者',
|
||
source: 'A',
|
||
pic: '封面URL',
|
||
mPic: '中封面URL',
|
||
sPic: '小封面URL',
|
||
albumName: '合集名',
|
||
albumId: '合集ID',
|
||
interval: '03:45',
|
||
qualities: { '128k': '4.2M', 'flac': '35M' }
|
||
}],
|
||
total: 100,
|
||
page: 1,
|
||
limit: 20,
|
||
allPage: 5,
|
||
source: 'A'
|
||
}
|
||
|
||
// 歌词返回格式（见下文歌词格式规范）
|
||
// 系统支持多种歌词格式，返回有的即可
|
||
return {
|
||
lrc: 'LRC格式歌词',
|
||
qrc: 'QRC逐字歌词',
|
||
krc: 'KRC歌词',
|
||
ttml: 'TTML歌词',
|
||
translate: '翻译歌词'
|
||
}
|
||
|
||
// 或直接返回歌词文本字符串（系统会自动判断格式）
|
||
return '[00:00.000]歌词内容\n[00:05.000]第二行歌词...'
|
||
```
|
||
|
||
---
|
||
|
||
## 插件基本结构
|
||
|
||
### 核心导入
|
||
|
||
```javascript
|
||
'use strict'
|
||
|
||
// 标准 Node.js 模块
|
||
const axios = require('axios')
|
||
const crypto = require('crypto')
|
||
```
|
||
|
||
### 配置区域
|
||
|
||
```javascript
|
||
// ========== 用户可配置区域 ==========
|
||
|
||
// 从 global.env 读取环境变量（JSON 格式）
|
||
const env = global.env || {}
|
||
|
||
// 服务端地址（用户可通过环境变量覆盖）
|
||
const API_BASE = env.SERVER_URL || 'https://your-server.com'
|
||
|
||
// API 密钥（用户通过环境变量设置）
|
||
const API_KEY = env.API_KEY || ''
|
||
|
||
// 当前平台标识（单平台插件固定值）
|
||
const PLATFORM = 'A'
|
||
|
||
// 支持的音质列表
|
||
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
|
||
```
|
||
|
||
### 导出结构
|
||
|
||
```javascript
|
||
// ========== 插件导出 ==========
|
||
|
||
module.exports = {
|
||
// 核心功能（必须实现）
|
||
musicSearch, // 内容搜索
|
||
getUrl, // 获取 URL
|
||
|
||
// 可选功能
|
||
getLyric, // 获取歌词
|
||
songList, // 列表详情
|
||
album, // 合集详情
|
||
hotSearch, // 热搜词
|
||
tipSearch, // 搜索提示
|
||
leaderboard, // 排行榜
|
||
|
||
// 插件信息（必须）
|
||
pluginInfo: {
|
||
info: {
|
||
id: 'A', // 平台标识
|
||
name: '平台A', // 显示名称
|
||
description: '平台A插件', // 描述
|
||
version: '3' // 版本号
|
||
},
|
||
env: [ // 环境变量配置
|
||
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
|
||
],
|
||
ext: [], // 扩展功能
|
||
quality: [ // 支持的音质
|
||
{ name: '标准音质', ui: '标', id: '128k' },
|
||
{ name: '高品音质', ui: 'HQ', id: '320k' },
|
||
{ name: '无损音质', ui: 'SQ', id: 'flac' }
|
||
],
|
||
supportFunc: [ // 支持的功能
|
||
'search_song',
|
||
'search_playlist',
|
||
'playlist',
|
||
'album',
|
||
'lyric'
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据格式规范
|
||
|
||
### 搜索结果统一格式
|
||
|
||
```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: { // 音质 -> 文件大小
|
||
'128k': '4.2M',
|
||
'320k': '8.5M',
|
||
'flac': '35M'
|
||
}
|
||
}
|
||
],
|
||
total: Number, // 总数量
|
||
page: Number, // 当前页码
|
||
limit: Number, // 每页数量
|
||
allPage: Number, // 总页数
|
||
source: String // 平台标识
|
||
}
|
||
```
|
||
|
||
### 歌词返回格式
|
||
|
||
**重要说明**：系统会自动判断歌词格式（lrc、qrc、krc、ttml 等），插件只需返回对应的歌词字段即可。
|
||
|
||
```javascript
|
||
// 推荐返回格式
|
||
{
|
||
lrc: String, // LRC 格式歌词
|
||
qrc: String, // QRC 逐字歌词
|
||
krc: String, // KRC 歌词
|
||
ttml: String, // TTML 歌词
|
||
translate: String // 翻译歌词
|
||
}
|
||
|
||
// 或者直接返回歌词文本字符串（系统会自动判断格式）
|
||
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 格式或纯文本 |
|
||
|
||
**注意事项**：
|
||
- 以上字段均为可选，返回有的即可
|
||
- 系统会自动识别歌词格式
|
||
- `translate` 用于翻译歌词
|
||
- 直接返回歌词文本字符串也是允许的，系统会尝试自动判断其格式
|
||
- 不同平台可能返回不同格式，如：平台A可能返回 `qrc` + `translate`，平台B可能返回 `lrc` + `tlyric`
|
||
|
||
### 列表详情统一格式
|
||
|
||
```javascript
|
||
{
|
||
list: [/* 内容列表，格式同搜索结果 */],
|
||
page: Number,
|
||
limit: Number,
|
||
total: Number,
|
||
source: String,
|
||
info: {
|
||
name: String, // 列表名
|
||
img: String, // 封面图
|
||
desc: String, // 描述
|
||
author: String // 创建者
|
||
}
|
||
}
|
||
```
|
||
|
||
### 合集详情统一格式
|
||
|
||
```javascript
|
||
{
|
||
list: [/* 内容列表，格式同搜索结果 */],
|
||
page: Number,
|
||
limit: Number,
|
||
total: Number,
|
||
source: String,
|
||
info: {
|
||
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 || {}
|
||
|
||
// 平台标识（固定值，单平台插件）
|
||
const PLATFORM = 'A'
|
||
|
||
// 服务端配置
|
||
const CONFIG = {
|
||
serverUrl: env.SERVER_URL || 'https://api.example.com',
|
||
apiKey: env.API_KEY || '',
|
||
timeout: 10000
|
||
}
|
||
|
||
// 支持的音质
|
||
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
|
||
|
||
// ==================== 工具函数 ====================
|
||
|
||
function sizeFormate(size) {
|
||
if (!size || isNaN(size)) return ''
|
||
if (size > 104857600) return (size / 104857600).toFixed(1) + 'MB'
|
||
if (size > 1048576) return (size / 1048576).toFixed(1) + 'MB'
|
||
if (size > 1024) return (size / 1024).toFixed(1) + 'KB'
|
||
return size + 'B'
|
||
}
|
||
|
||
function formatPlayTime(time) {
|
||
if (!time || isNaN(time)) return '--/--'
|
||
const m = Math.floor(time / 60)
|
||
const s = Math.floor(time % 60)
|
||
return m + ':' + s.toString().padStart(2, '0')
|
||
}
|
||
|
||
function formatArtistName(artistList) {
|
||
if (!artistList || !Array.isArray(artistList)) return ''
|
||
return artistList.map(a => a.name || a).join('、')
|
||
}
|
||
|
||
function decodeName(str) {
|
||
if (!str) return ''
|
||
return str
|
||
.replace(/'/g, "'")
|
||
.replace(/"/g, '"')
|
||
.replace(/</g, '<')
|
||
.replace(/>/g, '>')
|
||
.replace(/&/g, '&')
|
||
.replace(/ /g, ' ')
|
||
}
|
||
|
||
// ==================== 核心功能 ====================
|
||
|
||
async function musicSearch(str, page = 1, limit = 20) {
|
||
const params = { keyword: str, page, limit }
|
||
|
||
const url = CONFIG.serverUrl + '/search'
|
||
const response = await axios.get(url, {
|
||
params,
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
const data = response.data
|
||
|
||
const list = data.items.map(item => ({
|
||
id: String(item.id),
|
||
name: decodeName(item.name),
|
||
artists: formatArtistName(item.artists),
|
||
source: PLATFORM,
|
||
pic: item.picUrl || '',
|
||
mPic: item.picUrl || '',
|
||
sPic: item.picUrl || '',
|
||
albumName: decodeName(item.album?.name || ''),
|
||
albumId: String(item.album?.id || ''),
|
||
interval: formatPlayTime(item.duration),
|
||
qualities: {
|
||
'128k': sizeFormate(item.size128),
|
||
'320k': sizeFormate(item.size320),
|
||
'flac': sizeFormate(item.sizeFlac)
|
||
}
|
||
}))
|
||
|
||
return {
|
||
list,
|
||
total: data.total,
|
||
page,
|
||
limit,
|
||
allPage: Math.ceil(data.total / limit),
|
||
source: PLATFORM
|
||
}
|
||
}
|
||
|
||
async function getUrl(id, quality) {
|
||
if (!SUPPORT_QUALITIES.includes(quality)) {
|
||
quality = SUPPORT_QUALITIES[0]
|
||
}
|
||
|
||
const url = CONFIG.serverUrl + '/url'
|
||
const response = await axios.get(url, {
|
||
params: { id, quality },
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
const data = response.data
|
||
|
||
if (!data.url || !data.url.startsWith('http')) {
|
||
throw new Error('获取链接失败')
|
||
}
|
||
|
||
return data.url
|
||
}
|
||
|
||
async function getLyric(id) {
|
||
const url = CONFIG.serverUrl + '/lyric'
|
||
const response = await axios.get(url, {
|
||
params: { id },
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
const data = response.data
|
||
|
||
// 返回歌词对象，系统会自动判断格式
|
||
// 返回有的字段即可，不需要全部字段
|
||
return {
|
||
lrc: data.lrc || '',
|
||
qrc: data.qrc || '',
|
||
krc: data.krc || '',
|
||
ttml: data.ttml || '',
|
||
translate: data.translate || ''
|
||
}
|
||
|
||
// 或者直接返回歌词文本
|
||
// return data.lyric
|
||
}
|
||
|
||
async function songList(id, page = 1, limit = 20) {
|
||
const url = CONFIG.serverUrl + '/list'
|
||
const response = await axios.get(url, {
|
||
params: { id, page, limit },
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
const data = response.data
|
||
|
||
const list = data.items.map(item => ({
|
||
id: String(item.id),
|
||
name: decodeName(item.name),
|
||
artists: formatArtistName(item.artists),
|
||
source: PLATFORM,
|
||
pic: item.picUrl || '',
|
||
mPic: item.picUrl || '',
|
||
sPic: item.picUrl || '',
|
||
albumName: decodeName(item.album?.name || ''),
|
||
albumId: String(item.album?.id || ''),
|
||
interval: formatPlayTime(item.duration),
|
||
qualities: {}
|
||
}))
|
||
|
||
return {
|
||
list,
|
||
page,
|
||
limit,
|
||
total: data.total,
|
||
source: PLATFORM,
|
||
info: {
|
||
name: data.name || '',
|
||
img: data.cover || '',
|
||
desc: data.description || '',
|
||
author: data.creator?.name || ''
|
||
}
|
||
}
|
||
}
|
||
|
||
async function album(id, page = 1) {
|
||
const url = CONFIG.serverUrl + '/album'
|
||
const response = await axios.get(url, {
|
||
params: { id, page },
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
const data = response.data
|
||
|
||
const list = data.items.map(item => ({
|
||
id: String(item.id),
|
||
name: decodeName(item.name),
|
||
artists: formatArtistName(item.artists),
|
||
source: PLATFORM,
|
||
pic: item.picUrl || data.cover || '',
|
||
mPic: item.picUrl || data.cover || '',
|
||
sPic: item.picUrl || data.cover || '',
|
||
albumName: decodeName(data.name || ''),
|
||
albumId: String(id),
|
||
interval: formatPlayTime(item.duration),
|
||
qualities: {}
|
||
}))
|
||
|
||
return {
|
||
list,
|
||
page,
|
||
limit: 1000,
|
||
total: data.total,
|
||
source: PLATFORM,
|
||
info: {
|
||
name: data.name || '',
|
||
img: data.cover || '',
|
||
desc: data.description || '',
|
||
author: data.artist?.name || ''
|
||
}
|
||
}
|
||
}
|
||
|
||
async function hotSearch() {
|
||
const url = CONFIG.serverUrl + '/hotsearch'
|
||
const response = await axios.get(url, {
|
||
headers: { 'X-API-Key': CONFIG.apiKey },
|
||
timeout: CONFIG.timeout
|
||
})
|
||
|
||
return {
|
||
source: PLATFORM,
|
||
list: response.data.list || []
|
||
}
|
||
}
|
||
|
||
// ==================== 插件导出 ====================
|
||
|
||
module.exports = {
|
||
musicSearch,
|
||
getUrl,
|
||
getLyric,
|
||
songList,
|
||
album,
|
||
hotSearch,
|
||
|
||
pluginInfo: {
|
||
info: {
|
||
id: PLATFORM,
|
||
name: '平台A',
|
||
description: '平台A插件',
|
||
version: '3'
|
||
},
|
||
env: [
|
||
{ key: 'SERVER_URL', name: '服务端地址', description: '自定义服务端地址' },
|
||
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
|
||
],
|
||
ext: [],
|
||
quality: [
|
||
{ name: '标准音质', ui: '标', id: '128k' },
|
||
{ name: '高品音质', ui: 'HQ', id: '320k' },
|
||
{ name: '无损音质', ui: 'SQ', id: 'flac' }
|
||
],
|
||
supportFunc: ['search_song', 'search_playlist', 'playlist', 'album', 'lyric']
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 平台配置参考
|
||
|
||
### 各平台标识对照表
|
||
|
||
| 平台 | 标识 | 常见 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'],
|
||
B: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
|
||
C: ['128k', '320k', 'flac', 'flac24bit'],
|
||
D: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
|
||
E: ['128k', '320k', 'flac', 'flac24bit'],
|
||
F: ['128k', '320k', 'flac']
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 开发建议
|
||
|
||
### 多文件开发
|
||
|
||
**推荐使用多文件开发模式**，将不同功能模块分离，防止代码堆叠：
|
||
|
||
```
|
||
plugin/
|
||
├── index.js # 主入口，导出模块
|
||
├── search.js # 搜索相关功能
|
||
├── lyric.js # 歌词相关功能
|
||
├── playlist.js # 列表相关功能
|
||
├── utils.js # 工具函数
|
||
└── config.js # 配置常量
|
||
```
|
||
|
||
### 使用 ncc 打包
|
||
|
||
开发完成后，使用 `ncc` 将多文件打包为单文件即可：
|
||
|
||
```bash
|
||
# 安装 ncc
|
||
npm install -g @vercel/ncc
|
||
|
||
# 打包
|
||
ncc build index.js -o dist
|
||
|
||
# 输出的 dist/index.js 即为最终插件文件
|
||
```
|
||
|
||
**ncc 打包优点**：
|
||
- 将多文件合并为单文件，便于分发
|
||
- 自动处理依赖关系
|
||
- 保持 CommonJS 兼容性
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何从其他系统迁移到本系统？
|
||
|
||
**A**: 参考本文档的"从其他平台迁移指南"章节，主要修改点：
|
||
1. 将 `globalThis.lx.request` 改为 `axios`
|
||
2. 将事件监听改为函数导出
|
||
3. 修改数据返回格式
|
||
4. 添加 `module.exports` 导出
|
||
5. 环境变量从 `global.env` 读取
|
||
|
||
### Q2: 插件加载失败怎么办？
|
||
|
||
**A**: 检查以下几点：
|
||
1. 文件语法是否正确：`node -c your-plugin.js`
|
||
2. `pluginInfo` 是否完整
|
||
3. 导出的函数名是否正确
|
||
4. 依赖模块是否已安装（如 `axios`）
|
||
|
||
### Q3: 搜索返回空结果？
|
||
|
||
**A**: 检查：
|
||
1. API 请求是否成功（查看日志）
|
||
2. 响应数据解析是否正确
|
||
3. 数据格式是否符合规范
|
||
4. 返回的 `source` 是否与平台标识一致
|
||
|
||
### Q4: 播放失败？
|
||
|
||
**A**: 检查：
|
||
1. `getUrl` 返回的 URL 是否有效
|
||
2. URL 是否以 `http` 开头
|
||
3. 音质标识是否正确
|
||
4. 是否有跨域或权限问题
|
||
|
||
### Q5: 用户如何配置插件？
|
||
|
||
**A**: 用户通过设置界面配置环境变量：
|
||
|
||
```
|
||
SERVER_URL = 自定义服务端地址
|
||
API_KEY = 用户的API密钥
|
||
```
|
||
|
||
插件通过 `global.env` 读取：
|
||
|
||
```javascript
|
||
const env = global.env || {}
|
||
const SERVER_URL = env.SERVER_URL || '默认地址'
|
||
```
|
||
|
||
### Q6: 歌词格式应该返回什么？
|
||
|
||
**A**: 返回包含 `lrc`、`qrc`、`krc`、`ttml`、`translate` 等字段的对象，或直接返回歌词文本字符串。系统会自动判断歌词格式。
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 参考资源
|
||
|
||
- Node.js 官方文档
|
||
- axios 文档
|
||
- @vercel/ncc 打包工具
|
||
|
||
### 版本历史
|
||
|
||
- v1.0.3: 当前版本
|
||
- v1.0.0: 初始版本
|
||
|
||
---
|
||
|
||
**文档结束**
|