@aim-packages/downloader

由于在 electron 中没有找到好的下载库，以前使用过的 electron-dl 存在一些问题，代理设置也不方便，现在基于 node-downloader-helper 的增强型 Node.js 文件下载库。

✨ 额外功能

本库在 node-downloader-helper 基础上提供了两个额外功能：

1. 临时文件机制 - 下载过程中使用 .download 后缀的临时文件，下载完成并校验通过后才重命名为最终文件
2. SHA256 文件校验 - 下载完成后自动验证文件 SHA256 哈希值，确保文件完整性

📦 安装

pnpm add @aim-packages/downloader

🚀 快速开始

import { createDownloader } from '@aim-packages/downloader';

const downloader = createDownloader();

// 基本下载
const filePath = await downloader.download(
  'https://example.com/file.zip',
  '/path/to/destination/file.zip'
);

// 带 SHA256 校验的下载
await downloader.download(
  'https://example.com/file.zip',
  '/path/to/destination/file.zip',
  {
    sha256: 'expected-sha256-hash-value'
  }
);

💡 使用示例

使用 AbortSignal 取消下载

import { createDownloader, DownloadCancelledError } from '@aim-packages/downloader';

const downloader = createDownloader();
const abortController = new AbortController();

// 5 秒后取消下载
setTimeout(() => {
  abortController.abort();
}, 5000);

try {
  await downloader.download(
    'https://example.com/file.zip',
    '/path/to/destination/file.zip',
    {
      signal: abortController.signal
    }
  );
} catch (error) {
  if (error instanceof DownloadCancelledError) {
    console.log('下载已取消');
  }
}

使用代理下载

import { createDownloader } from '@aim-packages/downloader';
import { HttpsProxyAgent } from 'https-proxy-agent';

const downloader = createDownloader();
const proxyAgent = new HttpsProxyAgent('http://proxy.example.com:8080');

await downloader.download(
  'https://example.com/file.zip',
  '/path/to/destination/file.zip',
  {
    proxyAgent
  }
);

🔧 技术细节

临时文件机制

• 下载过程中使用 .download 后缀的临时文件（例如：file.zip.download）
• 下载完成后进行 SHA256 校验（如果提供）
• 校验通过后才重命名为最终文件（去掉 .download 后缀）
• 校验失败自动删除文件并抛出 HashMismatchError

SHA256 校验

• 如果提供了 sha256 选项，下载完成后会自动计算文件的 SHA256 哈希值
• 如果哈希值不匹配，会抛出 HashMismatchError 并删除文件
• 如果哈希值匹配，文件会重命名为最终文件名

📋 错误类型

HashMismatchError

Hash 校验失败错误。

class HashMismatchError extends Error {
  constructor(
    message?: string,
    public readonly expected?: string,
    public readonly actual?: string
  );
}

DownloadCancelledError

下载取消错误。当通过 AbortSignal 取消下载时抛出。

class DownloadCancelledError extends Error {
  constructor(message?: string);
}