aria2.js 的8个核心API逐一拆解：call、multicall、batch 完整用法清单

aria2.js 的8个核心API逐一拆解call、multicall、batch 完整用法清单【免费下载链接】aria2.jsJavaScript library for aria2, The next generation download utility.项目地址: https://gitcode.com/gh_mirrors/ar/aria2.jsaria2.js 是一个免费的 JavaScript 库用于通过 JSON-RPC 接口控制下一代下载工具 aria2支持 Node.js 与浏览器、HTTP/WebSocket 双通道、Promise API 且零第三方依赖。本文逐一拆解它的 8 个核心 API提供 call、multicall、batch、open/close、listMethods、events 的完整用法清单新手一次看懂、照抄即用。1️⃣ aria2.js 是什么30 秒快速上手aria2.js 把 aria2 的 RPC 接口封装成了简洁的 Promise API源码非常轻量核心文件只有 5 个入口与 API 实现src/Aria2.jsAria2 类HTTP / WebSocket 传输层src/JSONRPCClient.js统一错误类型src/JSONRPCError.js事件转 Promise 工具src/promiseEvent.js完整可运行示例example.js两步开始启动 aria2 并开启 RPC 接口aria2c --enable-rpc --rpc-listen-alltrue --rpc-allow-origin-all安装 aria2.js 并创建实例npm install aria2import Aria2 from aria2; const aria2 new Aria2(); // 默认连接 localhost:6800/jsonrpc默认配置与 aria2c 保持一致host为 localhost、port为 6800、path为/jsonrpcsecret对应--rpc-secret参数可选。2️⃣ 8 个核心 API 一览表序号API一句话说明1call单个方法调用使用频率最高的核心 API2multicall一次请求批量执行多个方法system.multicall3batchJSON-RPC 批量请求返回 Promise 数组、错误处理更灵活4open建立 WebSocket 长连接后续请求走长连接5close关闭 WebSocket回退到 HTTP 模式6listNotifications列出全部可用的下载事件通知7listMethods列出全部可用的 RPC 方法8events事件监听体系连接状态 下载进度实时推送3️⃣ call整个库的核心一行发起下载aria2.call(method, ...params)调用一个 aria2 RPC 方法参数按顺序传入。下面用addUri添加一个 magnet 磁力链接下载const guid await aria2.call(addUri, [magnet], { dir: /tmp });返回值是下载任务的 guid全局唯一标识之后暂停、移除、查询状态等操作都靠它。aria2.js 在call里帮你自动做了两件琐事见 src/Aria2.js 的prefix与addSecret自动补前缀写addUri即可不需要写全aria2.addUri自动带密钥构造时配置了secret每次调用都会自动附带 token无需手动传4️⃣ multicall批量调用一次搞定multicall是对system.multicall的封装把多个方法调用打包进一次请求按顺序返回结果数组。任何一个调用失败整体就会抛出异常。const calls [ [getFiles, guidA], [tellStatus, guidB], ]; const results await aria2.multicall(calls);适用场景需要同时拿到多个查询结果且要么全成、要么算失败。5️⃣ batch错误处理更灵活的批量请求batch是对 JSON-RPC 批量协议batch的封装入参与multicall写法完全相同但返回的是Promise 数组——每个请求独立结算某一项失败不会拖累其他项。const promises await aria2.batch(calls); const [r1, r2] await Promise.allSettled(promises);两者怎么选multicall调用量少、要原子性失败即整体报错batch调用量大、互不干扰可逐项 try/catch6️⃣ open / close在 WebSocket 与 HTTP 之间切换await aria2.open(); // 建立 WebSocket 长连接 await aria2.close(); // 关闭后续请求回退到 HTTP底层逻辑在 src/JSONRPCClient.js 的_send中WebSocket 已打开就发长连接否则走 HTTP切换完全自动无需手动指定通道。用 WebSocket 的最大好处是能实时接收 aria2 推送的通知下载开始、完成、出错等这是做下载进度面板的基础open/close内部借助 src/promiseEvent.js 把连接成功/失败转换成了 Promiseawait一行搞定。7️⃣ listNotifications / listMethods运行时自检能力两者分别封装system.listNotifications与system.listMethods并自动去掉结果中的aria2.前缀const notifications await aria2.listNotifications(); // [onDownloadStart, onDownloadPause, onDownloadComplete, ...] const methods await aria2.listMethods(); // [addUri, tellStatus, system.listMethods, ...]实用技巧拿到通知列表后循环订阅一次性挂上所有下载事件for (const name of await aria2.listNotifications()) { aria2.addEventListener(name, ({ detail }) console.log(name, detail)); }8️⃣ events监听下载进度的事件体系Aria2 类继承自 EventTarget可用addEventListener监听三类事件连接级open、close、error数据级input发出的数据、output接收的数据、notification任意通知aria2 通知onDownloadStart、onDownloadPause、onDownloadStop、onDownloadComplete、onDownloadError、onBtDownloadComplete等aria2.addEventListener(onDownloadStart, ({ params: [guid] }) { console.log(下载开始, guid); });调试小贴士把实例直接传给 src/debug.js 中的debug函数控制台就会打印全部事件与收发数据排查问题非常直观。9️⃣ 完整用法清单速查API签名返回值典型场景callcall(method, ...params)Promise添加/暂停/删除下载任务multicallmulticall(calls)Promise结果数组批量查询失败即抛错batchbatch(calls)PromisePromise 数组批量请求逐项容错openopen()Promise启用 WebSocket、接收推送closeclose()Promise释放长连接listNotificationslistNotifications()Promise事件名数组动态订阅全部通知listMethodslistMethods()Promise方法名数组接口自检eventsaddEventListener(...)监听器进度面板、日志输出 常见问题如何配置 secret构造时传入new Aria2({ secret: xxx })之后所有调用自动携带 token。调用失败长什么样以 src/JSONRPCError.js 中的JSONRPCError抛出携带code与data方便按错误码分支处理。浏览器里能用吗可以Node.js 与浏览器均支持浏览器中也可直接引用打包产物bundle.js通过window.Aria2使用。它到底走的哪个通道只要调用过open()且连接未断开就走 WebSocket否则自动走 HTTP无需手动切换。掌握这 8 个 API你就能用几行 JavaScript 把 aria2 的下载能力接入自己的 Node 服务或网页面板。建议结合example.js跑一遍开连接 →call添加磁力 → 监听onDownloadStart/onDownloadComplete一个最小下载中心就诞生了。【免费下载链接】aria2.jsJavaScript library for aria2, The next generation download utility.项目地址: https://gitcode.com/gh_mirrors/ar/aria2.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考