运行时 API

插件运行在 QuickJS 里，宿主在脚本之前注入一小组全局对象。这一页列出能用的全部东西，以及每一项的限制。

全局对象一览

标准的 ECMAScript 内建对象（Promise、JSON、Math、Date、Map、RegExp、encodeURIComponent 等）由 QuickJS 提供。没有 DOM、XMLHttpRequest、localStorage、文件与进程接口。

cerumusic.request

const res = await cerumusic.request(url, options);
// res = { statusCode, headers, body }

发起一次 HTTP(S) 请求，返回 Promise。也支持回调写法：cerumusic.request(url, options, (err, res) => {})。

options

返回值

function json(res) {
  let body = res.body;
  if (typeof body === 'string') {
    try { body = JSON.parse(body); } catch (_) { throw new Error('服务器返回的不是 JSON'); }
  }
  return body;
}

地址与失败

• 只允许 http / https，地址长度不超过 8192 字符，不能包含用户名密码（https://user:pass@host）。不合法的地址让 Promise reject，错误是「地址只支持无用户信息的 HTTP/HTTPS」。
• 最多跟随 5 次重定向；响应自动解压 gzip 与 brotli。
• 网络失败、超时、响应过大、请求次数超限，都会让 Promise reject（错误信息是宿主的固定文案，不含 URL）。

cerumusic.requestAll

const replies = await cerumusic.requestAll([
  { url: urlA, options: {} },
  { url: urlB, options: { headers: { Accept: 'application/json' } } },
]);
for (const r of replies) {
  if (r.error) { /* 这一个失败了 */ continue; }
  const { statusCode, body } = r.response;
}

并发发出多个请求（同时最多 8 个），结果按输入顺序返回，每一项是 { response } 或 { error }，Promise 本身不会因单个请求失败而 reject。一次最多 24 项，并且每一项都计入这次调用的请求次数上限。适合「先取列表，再并发取每一项的详情」这类场景，比串行 await 快得多。

cerumusic.storage

cerumusic.storage.set('session', { token, expires: Date.now() + 3600e3 });
const s = cerumusic.storage.get('session');   // 没有时是 undefined
cerumusic.storage.remove('session');

每个插件私有的持久化键值存储，同步调用。典型用途是缓存登录会话。

• 值会被序列化为 JSON，读取时还原；undefined 存为 null。
• 键不能为空，最长 128 个字符。整个存储序列化后不得超过 256 KiB，超过时 set 抛错。
• set 会立即交给宿主持久化；它跨调用、跨应用重启保留。
• 存储同样不是加密的。过期的令牌记得清理，缓存键里最好带上能让缓存失效的信息（例如服务器地址与密码的哈希），这样用户改了配置就不会读到旧会话。

cerumusic.config

用户在「配置」表单里填的值，一个普通对象，键就是 config 里声明的 key。没有声明表单时是 {}。始终防御性地读取：

const c = cerumusic.config || {};
const baseUrl = String(c.baseUrl || '').trim();
if (!baseUrl) throw new Error('请先在插件“配置”中填写服务器地址');

用户可能还没填，也可能填了带空格或尾部斜杠的值。校验并规范化它们是你的责任。

cerumusic.utils

crypto

buffer

cerumusic.utils.buffer.from(data, encoding) 与 bufToString(buffer, encoding)，与全局 Buffer.from 同源，encoding 可为 'base64' 或 'hex'。

lyric

环境信息

zlib / encoding

通用的字节工具，给需要自行解码来源专有歌词或数据格式的插件用。宿主不含任何来源专用的解码，XOR 密钥、分段格式与解析都写在你的脚本里。

wasm

QuickJS 没有 WebAssembly，需要运行 WebAssembly 模块的列表插件（例如音频指纹算法）通过宿主提供的受限桥执行。宿主不知道模块做什么：它只实例化你给出的字节，按你的要求调用导出函数或表项，并把模块对导入函数的每次调用交给你脚本里的处理函数回答。仅列表插件可用。

const inst = cerumusic.utils.wasm.instantiate(base64OrBytes, {
  a: { // 导入的模块名 → 函数名 → 处理函数
    b(x, y) { /* this 就是 inst；返回数字，不返回则视为 0 */ return 0; },
  },
}, { fuel: 600000000, maxMemory: 64 * 1024 * 1024 });
try {
  inst.call('exportName', 1, 2);          // 调用导出函数，返回第一个结果（数字）
  inst.callIndirect('tableName', 3, 4);   // 调用导出表的第 3 项，其余是参数
  const bytes = inst.read('memory', ptr, length);  // Uint8Array
  inst.write('memory', ptr, bytes);       // Uint8Array 或 base64 字符串
} finally {
  inst.close();
}

• 数值参数和结果都以 JavaScript 数字传递（i64 超过 2⁵³ 会丢失精度）；没有提供处理函数的导入返回 0。
• 模块只能导入函数；处理函数抛出的错误会中止这次调用，并成为调用方得到的错误。
• 限制：模块 ≤ 4 MiB，线性内存默认 64 MiB（最大 128 MiB），指令燃料默认 6 亿（最大 20 亿），同时最多 4 个实例；不能在处理函数里重入同一个实例。

限制一览

所有限制都是为了保证一个失控的脚本不会拖垮应用。超过任何一项都会让这次调用失败。