# electron-m3u8

**Repository Path**: ErGeAnan/electron-m3u8

## Basic Information

- **Project Name**: electron-m3u8
- **Description**: 基于 Electron + Vue3 开发的跨平台（优先适配 Windows）m3u8 视频下载工具，核心依赖 N_m3u8DL-RE 实现高性能、断点续传的 m3u8 分片下载，提供可视化操作界面，支持任务管理、实时进度监控、暂停/继续/删除任务等核心功能。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-16
- **Last Updated**: 2026-02-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# electron-m3u8

基于 Electron + Vue3 开发的跨平台（优先适配 Windows）m3u8 视频下载工具，核心依赖 `N_m3u8DL-RE` 实现高性能、断点续传的 m3u8 分片下载，提供可视化操作界面，支持任务管理、实时进度监控、暂停/继续/删除任务等核心功能。

## 🌟 核心功能

- 🖥️ 可视化操作界面：无需命令行，填写参数即可一键启动下载
- ⚡ 多线程下载：自定义下载线程数，提升下载速度
- 🔄 断点续传：暂停/终止任务后，重新启动可从断点继续下载（基于 N_m3u8DL-RE 原生能力）
- 📊 实时进度监控：展示下载进度、速度、已耗时、文件大小等核心指标
- 🎛️ 灵活配置：支持自定义保存路径、临时路径、文件名、线程数、超时时间等参数
- 🗑️ 任务管理：支持任务暂停、继续、删除，状态实时同步

## 📋 环境要求

| 依赖            | 版本要求                | 说明                                            |
|---------------|---------------------|-----------------------------------------------|
| Node.js       | ≥ 16.0.0            | 推荐 18.x LTS 版本                                |
| npm/yarn/pnpm | 任意                  | 包管理工具                                         |
| 操作系统          | Windows 10/11 (64位) | 优先适配 Windows（核心下载工具 N_m3u8DL-RE 为 Windows 版本） |
| ffmpeg        | 任意稳定版               | 用于视频分片合并（需配置路径）                               |

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/你的用户名/electron-m3u8-v1.git
cd electron-m3u8-v1
```

### 2. 安装依赖

```bash
# 使用 npm
npm install

# 或 yarn
yarn install

# 或 pnpm
pnpm install
```

### 3. 准备下载工具

将 `N_m3u8DL-RE.exe` 放入项目根目录的 `tools` 文件夹（无则新建），目录结构如下：

```
electron-m3u8-v1/
├── tools/
│   └── N_m3u8DL-RE.exe  # 核心下载工具
├── src/
├── package.json
└── ...
```

### 4. 配置 ffmpeg 路径

在项目的下载参数配置中，确保 `--decryption-binary-path` 指向本地 ffmpeg 可执行文件路径（如 `C:/Program Files/ffmpeg-full/bin/ffmpeg.exe`）。

### 5. 启动开发环境

```bash
# 启动渲染进程 + 主进程
npm run dev
```

### 6. 打包成桌面应用

```bash
# 打包 Windows 安装包/绿色版
npm run build
```

打包后的文件会输出到 `out` 目录。

## 📖 使用指南

### 基础操作流程

1. 启动应用后，在输入框填写以下核心参数：

- `m3u8 链接`：待下载的 m3u8 视频地址
- `保存文件名`：自定义下载后的视频文件名
- `保存路径`：视频最终保存目录
- `临时路径`：分片下载的临时目录（断点续传依赖此目录，请勿随意删除）
- `线程数`：下载分片的线程数（默认 128，可根据网络调整）

2. 点击「开始下载」，任务会加入列表并自动启动
3. 任务列表中可查看实时进度、速度、耗时等信息
4. 支持对任务执行「暂停」「继续」「删除」操作：

- 暂停：终止当前下载进程（保留临时文件，支持续传）
- 继续：重新启动下载进程，自动跳过已下载分片
- 删除：终止进程并移除任务（可选保留/删除临时文件）

### 核心参数说明

| 参数     | 作用             | 默认值 |
|--------|----------------|-----|
| 线程数    | 分片下载的并发线程数     | 128 |
| 请求超时时间 | HTTP 请求超时时间（秒） | 100 |
| 重试次数   | 分片下载失败后的重试次数   | 3   |
| 自动合并   | 下载完成后自动合并分片    | 开启  |
| 删除临时文件 | 合并完成后删除分片文件    | 开启  |

## 🔧 技术栈

- **主进程**：Electron（IPC 通信、子进程管理、窗口管理）
- **渲染进程**：Vue3 + Vite（响应式界面、状态管理）
- **核心工具**：N_m3u8DL-RE（m3u8 分片下载、解密、合并）
- **进程通信**：Electron IPC（主进程 ↔ 渲染进程 状态同步）
- **依赖管理**：npm/yarn/pnpm

## ❓ 常见问题

### 1. 暂停后继续下载报错「Failed to serialize arguments」

- **原因**：Electron IPC 无法序列化 Vue 响应式对象
- **解决**：发送 IPC 消息前，将响应式对象转为纯普通对象：
  ```typescript
  const plainTask = JSON.parse(JSON.stringify(task));
  mainWindow.webContents.send('task-progress-update', plainTask);
  ```

### 2. Windows 系统暂停任务无效

- **原因**：Windows 不支持 `SIGSTOP` 信号，无法挂起进程
- **解决**：暂停时终止进程，继续时复用原参数重启（依赖 N_m3u8DL-RE 断点续传能力），核心逻辑：
  ```typescript
  // 暂停：终止进程 + 标记状态
  taskProcess.process.kill();
  task.status = 'waiting';

  // 继续：重启进程 + 断点续传
  executeDownloadCommand(task); // 复用原参数启动
  ```

### 3. 断点续传不生效

- **检查项**：
  1. 继续下载时，`保存文件名`/`保存路径`/`临时路径` 需与暂停前完全一致
  2. 临时目录未被手动删除（分片文件存储在此）
  3. N_m3u8DL-RE 启动参数包含 `--check-segments-count=True`（默认开启）

### 4. 下载完成后无法合并视频

- **原因**：ffmpeg 路径配置错误或未安装
- **解决**：
  1. 确认本地已安装 ffmpeg
  2. 在下载参数中正确配置 `--decryption-binary-path` 指向 ffmpeg.exe 路径

## 📄 许可证

本项目仅用于个人学习使用，请勿用于商业用途。核心下载工具 `N_m3u8DL-RE` 遵循其原始开源协议。

## 🙏 致谢

- [N_m3u8DL-RE](https://github.com/nilaoda/N_m3u8DL-RE)：高性能 m3u8 下载核心
- [Electron](https://www.electronjs.org/)：跨平台桌面应用开发框架
- [Vue3](https://vuejs.org/)：前端响应式框架

## 📞 反馈

如有问题或建议，可通过以下方式反馈：

- Issue：提交 GitHub Issue
- 邮箱：你的邮箱地址
- 备注：提交问题时请附上日志信息（如下载失败的命令行输出、报错截图），便于快速定位问题。

### 总结

1. 项目核心是基于 Electron 封装 N_m3u8DL-RE，提供可视化 m3u8 下载能力，优先适配 Windows 系统；
2. 断点续传、暂停/继续是核心特性，需保证临时目录不被删除、参数一致性；
3. 常见问题主要集中在 IPC 序列化、Windows 进程管理、ffmpeg 配置三个方面，按文档指引可快速解决。