hyperdown.js

HyperDown.js 核心功能与使用指南

简介

HyperDown.js 是一个轻量级的 JavaScript 下载管理库，支持浏览器和 Node.js 环境，它提供多任务并行下载、断点续传、下载进度监控等功能，适用于大文件下载、多资源批量获取等场景。

核心功能

安装方式

npm 安装（Node.js 环境）

npm install hyperdown

浏览器直接引入

<script src="https://unpkg.com/hyperdown/dist/hyperdown.min.js"></script>

快速开始

基础用法（Node.js）

const HyperDown = require('hyperdown');
// 创建下载管理器
const downloader = new HyperDown();
// 添加下载任务
downloader.addTask({
  id: 'file1',                    // 任务唯一标识
  url: 'https://example.com/file.zip', // 下载地址
  targetPath: './file.zip'        // 保存路径（仅 Node.js 可用）
});
// 开始下载
downloader.start();
// 监听下载完成事件
downloader.on('complete', (task) => {
  console.log(`${task.id} 下载完成`);
});

浏览器环境用法

// 假设已通过 <script> 引入 HyperDown.js
const downloader = new HyperDown();
downloader.addTask({
  id: 'image1',
  url: 'https://example.com/image.png',
  onProgress: (progress) => {
    console.log(`下载进度：${progress}%`);
  }
});
downloader.start();

配置参数说明

错误处理

常见错误类型及处理方法：
| 错误类型 | 触发场景 | 处理方法 |
|———————|———————————-|————————————–|
| NetworkError | 网络中断或跨域请求被阻止 | 检查网络连接，配置代理或 CORS |
| FileAccessError | 无写入权限（Node.js） | 检查目标路径权限 |
| HashMismatch | 文件校验失败（启用校验时） | 重新下载或检查服务器文件完整性 |

示例代码：

downloader.on('error', (err, task) => {
  if (err.type === 'NetworkError') {
    console.error(`${task.id} 网络错误，正在重试...`);
  } else if (err.type === 'FileAccessError') {
    console.error(`无法写入文件：${task.targetPath}`);
  }
});

高级特性

暂停与恢复任务

// 暂停所有任务
downloader.pauseAll();
// 恢复指定任务
downloader.resumeTask('file1');

优先级队列管理

downloader.addTask({ id: 'low', url: '...', priority: 1 }); // 低优先级
downloader.addTask({ id: 'high', url: '...', priority: 5 }); // 高优先级

文件分片下载（Node.js）

const fs = require('fs');
const downloader = new HyperDown();
downloader.addTask({
  id: 'large-file',
  url: 'https://example.com/large-file.tar.gz',
  chunkSize: 1024  1024, // 每片 1MB
  onChunkDownloaded: (chunkData, index) => {
    fs.appendFileSync('./large-file.part', chunkData); // 自定义分片存储逻辑
  }
});

相关问题与解答

Q1：如何配置代理服务器？

A：在 Node.js 环境中，可以通过设置 proxy 选项：

const downloader = new HyperDown({
  proxy: 'http://127.0.0.1:8080' // 代理地址
});

浏览器环境需通过 fetch 代理配置或自行封装请求。

Q2：如何下载需要身份验证的资源？

A：在任务配置中添加认证信息：

downloader.addTask({
  url: 'https://private-repo/file.zip',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN' // 或 Basic 认证头
  }
});