miao-moe/Koneko_api_for_QZ-Music

Fork 0

Files

miao-moe c6eeb253d0 Update to v0.0.4: add aggregated plugins with API failover, update docs

2026-06-20 12:31:39 +08:00

20 KiB

Raw Permalink Blame History

QZ Music 插件开发帮助文档

概述

本文档用于指导开发者编写 QZ Music 音源插件。QZ Music 使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 module.exports 导出功能接口。

与 LX Music 的区别

特性	QZ Music	LX Music
运行时	Node.js	JavaScript 运行时
模块规范	CommonJS	全局事件监听
导出方式	`module.exports`	`send(EVENT_NAMES.inited)`
通信方式	直接函数调用	事件驱动
HTTP 请求	`axios` 或内置 `httpFetch`	`globalThis.lx.request`

插件类型

QZ Music 插件属于完整音源插件，核心功能包括：

搜索歌曲
获取音频播放 URL
获取歌词
获取歌单/专辑信息
获取热搜/排行榜

核心设计原则

1. 单平台原则（重要）

每个插件只支持一个音乐平台，例如：

✅ 网易云音乐插件（仅支持 wy）
✅ QQ音乐插件（仅支持 tx）
❌ 聚合插件（同时支持 wy + tx + kw）

原因说明：

用户向插件传配置只能通过环境变量（env）
如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
单平台插件更清晰，维护成本低，不易出现"代码屎山"

如需多平台支持：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。

2. 配置方式

通过 process.env 或插件内置的 env 配置读取环境变量：

// 读取用户配置的 API 密钥
const API_KEY = process.env.API_KEY || ''

// 读取自定义服务端地址
const CUSTOM_SERVER = process.env.SERVER_URL || '默认地址'

3. 支持的音质标识

标识	说明
`128k`	标准音质，MP3 格式
`320k`	高品音质，MP3 格式
`flac`	无损音质，16bit FLAC
`flac24bit`	无损音质，24bit FLAC
`hires`	高解析度无损

从 LX Music 迁移指南

迁移对照表

LX Music	QZ Music	说明
`globalThis.lx`	`require` 模块	不再需要全局对象
`globalThis.lx.request`	`axios` 或 `httpFetch`	使用标准 HTTP 库
`globalThis.lx.env`	`process.env`	环境变量读取方式
`on(EVENT_NAMES.request, ...)`	直接导出函数	改为函数导出
`send(EVENT_NAMES.inited, ...)`	`module.exports`	改为模块导出
`musicInfo.songmid`	`musicInfo.id`	字段名可能不同
`info.type`	`quality` 参数	音质参数位置

迁移步骤

步骤 1：修改模块导入

LX Music 原代码：

const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx

QZ Music 新代码：

const axios = require('axios')
const crypto = require('crypto')

// 环境变量
const API_KEY = process.env.API_KEY || ''

步骤 2：修改 HTTP 请求

LX Music 原代码：

function httpRequest(url) {
  return new Promise((resolve, reject) => {
    request(url, { headers }, (err, resp) => {
      if (err) return reject(err)
      resolve(resp.body)
    })
  })
}

QZ Music 新代码：

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：修改函数导出

LX Music 原代码：

// 事件监听方式
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
})

QZ Music 新代码：

// 直接导出函数
module.exports = {
  // 搜索功能
  musicSearch,
  
  // 获取音频 URL
  getUrl,
  
  // 获取歌词
  getLyric,
  
  // 获取歌单
  songList,
  
  // 获取专辑
  album,
  
  // 获取热搜
  hotSearch,
  
  // 插件信息
  pluginInfo: {
    info: { id: 'wy', name: '网易云', version: '3' },
    quality: [...],
    supportFunc: [...]
  }
}

步骤 4：修改返回数据格式

LX Music 原代码：

// 直接返回 URL 字符串
return 'https://example.com/music.mp3'

// 或返回歌词对象
return {
  lyric: '[00:00.000]歌词内容',
  tlyric: '[00:00.000]翻译歌词'
}

QZ Music 新代码：

// 搜索返回统一格式
return {
  list: [{
    id: '123456',
    name: '歌曲名',
    artists: '歌手名',
    source: 'wy',
    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: 'wy'
}

// 歌词返回格式
return {
  lyric: '歌词内容',
  tlyric: '翻译歌词'
}

插件基本结构

文件头部注释

/**
 * @name 网易云音乐源
 * @description QZ Music 音源插件
 * @version 3.0.0
 * @author 开发者
 * @homepage https://github.com/your-repo
 * @license MIT
 * 
 * 支持平台: 网易云音乐 (wy)
 * 支持音质: 128k, 320k, flac, flac24bit, hires
 */

核心导入

'use strict'

// 标准 Node.js 模块
const axios = require('axios')
const crypto = require('crypto')

配置区域

// ========== 用户可配置区域 ==========

// 服务端地址（用户可通过环境变量覆盖）
const API_BASE = process.env.SERVER_URL || 'https://your-server.com'

// API 密钥（用户通过环境变量设置）
const API_KEY = process.env.API_KEY || ''

// 当前平台标识（单平台插件固定值）
const PLATFORM = 'wy'  // wy: 网易云, tx: QQ音乐, kw: 酷我, kg: 酷狗, mg: 咪咕

// 支持的音质列表
const SUPPORT_QUALITIES = ['128k', '320k', 'flac', 'flac24bit', 'hires']

导出结构

// ========== 插件导出 ==========

module.exports = {
  // 核心功能（必须实现）
  musicSearch,      // 歌曲搜索
  getUrl,           // 获取音频 URL
  
  // 可选功能
  getLyric,         // 获取歌词
  songList,         // 歌单详情
  album,            // 专辑详情
  hotSearch,        // 热搜词
  tipSearch,        // 搜索提示
  leaderboard,      // 排行榜
  
  // 插件信息（必须）
  pluginInfo: {
    info: {
      id: 'wy',                    // 平台标识
      name: '网易云',               // 显示名称
      description: '网易云音乐插件', // 描述
      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' },
      { name: 'Hi-Res', ui: 'HR', id: 'hires' }
    ],
    supportFunc: [                  // 支持的功能
      'search_song',
      'search_playlist',
      'playlist',
      'album',
      'lyric'
    ]
  }
}

数据格式规范

搜索结果统一格式

{
  list: [
    {
      id: String,              // 歌曲唯一标识
      name: String,             // 歌曲名（已解码 HTML 实体）
      artists: String,          // 歌手名（用 "、" 分隔）
      source: String,           // 平台标识: 'wy'/'tx'/'kw'/'kg'/'mg'
      pic: String,              // 大封面图 URL（500x500）
      mPic: String,             // 中封面图 URL（300x300）
      sPic: String,             // 小封面图 URL（150x150）
      albumName: String,        // 专辑名
      albumId: String,          // 专辑 ID
      interval: String,         // 时长 "mm:ss"
      qualities: {              // 音质 -> 文件大小
        '128k': '4.2M',
        '320k': '8.5M',
        'flac': '35M',
        'hires': '68M'
      }
    }
  ],
  total: Number,               // 总数量
  page: Number,                // 当前页码
  limit: Number,               // 每页数量
  allPage: Number,             // 总页数
  source: String               // 平台标识
}

歌词统一格式

{
  lyric: String,       // 普通歌词 (LRC 格式)
  tlyric: String,      // 翻译歌词
  qrc: String,         // 逐字歌词 (QRC 格式)
  roma: String         // 音译歌词
}

// 注意：至少返回 lyric 或 qrc 之一

歌单详情统一格式

{
  list: [/* 歌曲列表，格式同搜索结果 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
    name: String,        // 歌单名
    img: String,         // 封面图
    desc: String,        // 描述
    author: String       // 作者
  }
}

专辑详情统一格式

{
  list: [/* 歌曲列表，格式同搜索结果 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
    name: String,        // 专辑名
    img: String,         // 封面图
    desc: String,        // 描述
    author: String       // 艺术家
  }
}

示例代码详解

完整插件模板

/**
 * @name 网易云音乐源
 * @description QZ Music 音源插件示例
 * @version 3.0.0
 * @author 开发者
 * 
 * 支持平台: 网易云音乐 (wy)
 * 支持音质: 128k, 320k, flac
 */

'use strict'

// ==================== 核心导入 ====================

const axios = require('axios')
const crypto = require('crypto')

// ==================== 配置区域 ====================

// 平台标识（固定值，单平台插件）
const PLATFORM = 'wy'

// 服务端配置
const CONFIG = {
  serverUrl: process.env.SERVER_URL || 'https://api.example.com',
  apiKey: process.env.API_KEY || '',
  timeout: 10000
}

// 支持的音质
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']

// ==================== 工具函数 ====================

/**
 * 文件大小格式化
 * @param {number} size - 字节数
 * @returns {string} 格式化后的字符串
 */
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'
}

/**
 * 播放时间格式化
 * @param {number} time - 秒数
 * @returns {string} 格式化后的字符串
 */
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')
}

/**
 * 歌手名称格式化
 * @param {Array} singerList - 歌手列表
 * @returns {string} 用 "、" 连接的歌手名
 */
function formatSingerName(singerList) {
  if (!singerList || !Array.isArray(singerList)) return ''
  return singerList.map(s => s.name || s).join('、')
}

/**
 * HTML 实体解码
 * @param {string} str - 含 HTML 实体的字符串
 * @returns {string} 解码后的字符串
 */
function decodeName(str) {
  if (!str) return ''
  return str
    .replace(/&apos;/g, "'")
    .replace(/&quot;/g, '"')
    .replace(/&lt;/g, '<')
    .replace(/&gt;/g, '>')
    .replace(/&amp;/g, '&')
    .replace(/&nbsp;/g, ' ')
}

// ==================== 核心功能 ====================

/**
 * 搜索歌曲
 * @param {string} str - 搜索关键词
 * @param {number} page - 页码，从 1 开始
 * @param {number} limit - 每页数量
 * @returns {Promise<Object>} 搜索结果
 */
async function musicSearch(str, page = 1, limit = 20) {
  // 构造请求参数
  const params = {
    keyword: str,
    page: page,
    limit: 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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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: page,
    limit: limit,
    allPage: Math.ceil(data.total / limit),
    source: PLATFORM
  }
}

/**
 * 获取音乐播放 URL
 * @param {string} songId - 歌曲 ID
 * @param {string} quality - 音质标识
 * @returns {Promise<string>} 播放 URL
 */
async function getUrl(songId, quality) {
  // 检查音质
  if (!SUPPORT_QUALITIES.includes(quality)) {
    quality = SUPPORT_QUALITIES[0]
  }
  
  // 发送请求
  const url = `${CONFIG.serverUrl}/music/url`
  const response = await axios.get(url, {
    params: { id: songId, quality: 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
}

/**
 * 获取歌词
 * @param {string} songId - 歌曲 ID
 * @returns {Promise<Object>} 歌词对象
 */
async function getLyric(songId) {
  const url = `${CONFIG.serverUrl}/music/lyric`
  const response = await axios.get(url, {
    params: { id: songId },
    headers: { 'X-API-Key': CONFIG.apiKey },
    timeout: CONFIG.timeout
  })
  
  const data = response.data
  
  return {
    lyric: data.lyric || '',
    tlyric: data.tlyric || ''
  }
}

/**
 * 获取歌单详情
 * @param {string} id - 歌单 ID
 * @param {number} page - 页码
 * @param {number} limit - 每页数量
 * @returns {Promise<Object>} 歌单详情
 */
async function songList(id, page = 1, limit = 20) {
  const url = `${CONFIG.serverUrl}/playlist`
  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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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 || ''
    }
  }
}

/**
 * 获取专辑详情
 * @param {string} id - 专辑 ID
 * @param {number} page - 页码
 * @returns {Promise<Object>} 专辑详情
 */
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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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 || ''
    }
  }
}

/**
 * 获取热搜词
 * @returns {Promise<Object>} 热搜列表
 */
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: '网易云',
      description: '网易云音乐插件',
      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 字段
网易云音乐	`wy`	`id`, `songmid`
QQ音乐	`tx`	`songmid`, `id`
酷我音乐	`kw`	`rid`, `id`, `hash`
酷狗音乐	`kg`	`hash`, `id`
咪咕音乐	`mg`	`copyrightId`, `id`
汽水音乐	`qx`	`id`

音质支持参考

// 各平台常见音质配置
const PLATFORM_QUALITIES = {
  wy: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  tx: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  kw: ['128k', '320k', 'flac', 'flac24bit'],
  kg: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  mg: ['128k', '320k', 'flac', 'flac24bit'],
  qx: ['128k', '320k', 'flac']
}

常见问题

Q1: 如何从 LX Music 迁移到 QZ Music？

A: 参考本文档的"从 LX Music 迁移指南"章节，主要修改点：

将 globalThis.lx.request 改为 axios
将事件监听改为函数导出
修改数据返回格式
添加 module.exports 导出

Q2: 插件加载失败怎么办？

A: 检查以下几点：

文件语法是否正确：node -c your-plugin.js
pluginInfo 是否完整
导出的函数名是否正确
依赖模块是否已安装（如 axios）

Q3: 搜索返回空结果？

A: 检查：

API 请求是否成功（查看日志）
响应数据解析是否正确
数据格式是否符合规范
返回的 source 是否与平台标识一致

Q4: 音频无法播放？

A: 检查：

getUrl 返回的 URL 是否有效
URL 是否以 http 开头
音质标识是否正确
是否有跨域或权限问题

Q5: 用户如何配置插件？

A: 用户通过 QZ Music 的设置界面配置环境变量：

SERVER_URL = 自定义服务端地址
API_KEY = 用户的API密钥

插件通过 process.env 读取：

const SERVER_URL = process.env.SERVER_URL || '默认地址'

附录

参考资源

QZ Music 官方文档
提供的音源文件（lx&qz官方部分音源）
Node.js 官方文档
axios 文档

版本历史

v1.0.0 (2024-05-28): 初始版本

文档结束

20 KiB Raw Permalink Blame History Unescape Escape

QZ Music 插件开发帮助文档

目录

概述

与 LX Music 的区别

插件类型

核心设计原则

1. 单平台原则（重要）

2. 配置方式

3. 支持的音质标识

从 LX Music 迁移指南

迁移对照表

迁移步骤

步骤 1：修改模块导入

步骤 2：修改 HTTP 请求

步骤 3：修改函数导出

步骤 4：修改返回数据格式

插件基本结构

文件头部注释

核心导入

配置区域

导出结构

数据格式规范

搜索结果统一格式

歌词统一格式

歌单详情统一格式

专辑详情统一格式

示例代码详解

完整插件模板

平台配置参考

各平台标识对照表

音质支持参考

常见问题

Q1: 如何从 LX Music 迁移到 QZ Music？

Q2: 插件加载失败怎么办？

Q3: 搜索返回空结果？

Q4: 音频无法播放？

Q5: 用户如何配置插件？

附录

参考资源

版本历史

20 KiB

Raw Permalink Blame History