aria2.js 的8個(gè)核心API逐一拆解call、multicall、batch 完整用法清單【免費(fèi)下載鏈接】aria2.jsJavaScript library for aria2, The next generation download utility.項(xiàng)目地址: https://gitcode.com/gh_mirrors/ar/aria2.jsaria2.js 是一個(gè)免費(fèi)的 JavaScript 庫(kù)用于通過 JSON-RPC 接口控制下一代下載工具 aria2支持 Node.js 與瀏覽器、HTTP/WebSocket 雙通道、Promise API 且零第三方依賴。本文逐一拆解它的 8 個(gè)核心 API提供 call、multicall、batch、open/close、listMethods、events 的完整用法清單新手一次看懂、照抄即用。1?? aria2.js 是什么30 秒快速上手aria2.js 把 aria2 的 RPC 接口封裝成了簡(jiǎn)潔的 Promise API源碼非常輕量核心文件只有 5 個(gè)入口與 API 實(shí)現(xiàn)src/Aria2.jsAria2 類HTTP / WebSocket 傳輸層src/JSONRPCClient.js統(tǒng)一錯(cuò)誤類型src/JSONRPCError.js事件轉(zhuǎn) Promise 工具src/promiseEvent.js完整可運(yùn)行示例example.js兩步開始啟動(dòng) aria2 并開啟 RPC 接口aria2c --enable-rpc --rpc-listen-alltrue --rpc-allow-origin-all安裝 aria2.js 并創(chuàng)建實(shí)例npm install aria2import Aria2 from aria2; const aria2 new Aria2(); // 默認(rèn)連接 localhost:6800/jsonrpc默認(rèn)配置與 aria2c 保持一致host為 localhost、port為 6800、path為/jsonrpcsecret對(duì)應(yīng)--rpc-secret參數(shù)可選。2?? 8 個(gè)核心 API 一覽表序號(hào)API一句話說明1call單個(gè)方法調(diào)用使用頻率最高的核心 API2multicall一次請(qǐng)求批量執(zhí)行多個(gè)方法system.multicall3batchJSON-RPC 批量請(qǐng)求返回 Promise 數(shù)組、錯(cuò)誤處理更靈活4open建立 WebSocket 長(zhǎng)連接后續(xù)請(qǐng)求走長(zhǎng)連接5close關(guān)閉 WebSocket回退到 HTTP 模式6listNotifications列出全部可用的下載事件通知7listMethods列出全部可用的 RPC 方法8events事件監(jiān)聽體系連接狀態(tài) 下載進(jìn)度實(shí)時(shí)推送3?? call整個(gè)庫(kù)的核心一行發(fā)起下載aria2.call(method, ...params)調(diào)用一個(gè) aria2 RPC 方法參數(shù)按順序傳入。下面用addUri添加一個(gè) magnet 磁力鏈接下載const guid await aria2.call(addUri, [magnet], { dir: /tmp });返回值是下載任務(wù)的 guid全局唯一標(biāo)識(shí)之后暫停、移除、查詢狀態(tài)等操作都靠它。aria2.js 在call里幫你自動(dòng)做了兩件瑣事見 src/Aria2.js 的prefix與addSecret自動(dòng)補(bǔ)前綴寫addUri即可不需要寫全aria2.addUri自動(dòng)帶密鑰構(gòu)造時(shí)配置了secret每次調(diào)用都會(huì)自動(dòng)附帶 token無(wú)需手動(dòng)傳4?? multicall批量調(diào)用一次搞定multicall是對(duì)system.multicall的封裝把多個(gè)方法調(diào)用打包進(jìn)一次請(qǐng)求按順序返回結(jié)果數(shù)組。任何一個(gè)調(diào)用失敗整體就會(huì)拋出異常。const calls [ [getFiles, guidA], [tellStatus, guidB], ]; const results await aria2.multicall(calls);適用場(chǎng)景需要同時(shí)拿到多個(gè)查詢結(jié)果且要么全成、要么算失敗。5?? batch錯(cuò)誤處理更靈活的批量請(qǐng)求batch是對(duì) JSON-RPC 批量協(xié)議batch的封裝入?yún)⑴cmulticall寫法完全相同但返回的是Promise 數(shù)組——每個(gè)請(qǐng)求獨(dú)立結(jié)算某一項(xiàng)失敗不會(huì)拖累其他項(xiàng)。const promises await aria2.batch(calls); const [r1, r2] await Promise.allSettled(promises);兩者怎么選multicall調(diào)用量少、要原子性失敗即整體報(bào)錯(cuò)batch調(diào)用量大、互不干擾可逐項(xiàng) try/catch6?? open / close在 WebSocket 與 HTTP 之間切換await aria2.open(); // 建立 WebSocket 長(zhǎng)連接 await aria2.close(); // 關(guān)閉后續(xù)請(qǐng)求回退到 HTTP底層邏輯在 src/JSONRPCClient.js 的_send中WebSocket 已打開就發(fā)長(zhǎng)連接否則走 HTTP切換完全自動(dòng)無(wú)需手動(dòng)指定通道。用 WebSocket 的最大好處是能實(shí)時(shí)接收 aria2 推送的通知下載開始、完成、出錯(cuò)等這是做下載進(jìn)度面板的基礎(chǔ)open/close內(nèi)部借助 src/promiseEvent.js 把連接成功/失敗轉(zhuǎn)換成了 Promiseawait一行搞定。7?? listNotifications / listMethods運(yùn)行時(shí)自檢能力兩者分別封裝system.listNotifications與system.listMethods并自動(dòng)去掉結(jié)果中的aria2.前綴const notifications await aria2.listNotifications(); // [onDownloadStart, onDownloadPause, onDownloadComplete, ...] const methods await aria2.listMethods(); // [addUri, tellStatus, system.listMethods, ...]實(shí)用技巧拿到通知列表后循環(huán)訂閱一次性掛上所有下載事件for (const name of await aria2.listNotifications()) { aria2.addEventListener(name, ({ detail }) console.log(name, detail)); }8?? events監(jiān)聽下載進(jìn)度的事件體系A(chǔ)ria2 類繼承自 EventTarget可用addEventListener監(jiān)聽三類事件連接級(jí)open、close、error數(shù)據(jù)級(jí)input發(fā)出的數(shù)據(jù)、output接收的數(shù)據(jù)、notification任意通知aria2 通知onDownloadStart、onDownloadPause、onDownloadStop、onDownloadComplete、onDownloadError、onBtDownloadComplete等aria2.addEventListener(onDownloadStart, ({ params: [guid] }) { console.log(下載開始, guid); });調(diào)試小貼士把實(shí)例直接傳給 src/debug.js 中的debug函數(shù)控制臺(tái)就會(huì)打印全部事件與收發(fā)數(shù)據(jù)排查問題非常直觀。9?? 完整用法清單速查API簽名返回值典型場(chǎng)景callcall(method, ...params)Promise添加/暫停/刪除下載任務(wù)multicallmulticall(calls)Promise結(jié)果數(shù)組批量查詢失敗即拋錯(cuò)batchbatch(calls)PromisePromise 數(shù)組批量請(qǐng)求逐項(xiàng)容錯(cuò)openopen()Promise啟用 WebSocket、接收推送closeclose()Promise釋放長(zhǎng)連接listNotificationslistNotifications()Promise事件名數(shù)組動(dòng)態(tài)訂閱全部通知listMethodslistMethods()Promise方法名數(shù)組接口自檢eventsaddEventListener(...)監(jiān)聽器進(jìn)度面板、日志輸出 常見問題如何配置 secret構(gòu)造時(shí)傳入new Aria2({ secret: xxx })之后所有調(diào)用自動(dòng)攜帶 token。調(diào)用失敗長(zhǎng)什么樣以 src/JSONRPCError.js 中的JSONRPCError拋出攜帶code與data方便按錯(cuò)誤碼分支處理。瀏覽器里能用嗎可以Node.js 與瀏覽器均支持瀏覽器中也可直接引用打包產(chǎn)物bundle.js通過window.Aria2使用。它到底走的哪個(gè)通道只要調(diào)用過open()且連接未斷開就走 WebSocket否則自動(dòng)走 HTTP無(wú)需手動(dòng)切換。掌握這 8 個(gè) API你就能用幾行 JavaScript 把 aria2 的下載能力接入自己的 Node 服務(wù)或網(wǎng)頁(yè)面板。建議結(jié)合example.js跑一遍開連接 →call添加磁力 → 監(jiān)聽onDownloadStart/onDownloadComplete一個(gè)最小下載中心就誕生了?！久赓M(fèi)下載鏈接】aria2.jsJavaScript library for aria2, The next generation download utility.項(xiàng)目地址: https://gitcode.com/gh_mirrors/ar/aria2.js創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考