已知限制与注意事项

本文档汇总了 FlowPick 当前版本的技术限制和已知问题。了解这些限制有助于避免在使用过程中遇到意外情况。

限制等级说明

本文档中的每个限制按影响程度分为三个等级：

文件大小限制

Blob 模式硬限制

当浏览器不支持 File System Access API 或 StreamSaver.js 时，FlowPick 降级为 Blob 模式写入文件。此模式存在硬性大小限制：

原因：Blob 模式需要将整个文件加载到内存中，超过 1.5GB 可能导致浏览器崩溃或页面无响应。

解决方案：使用 Chrome 86+ 或 Edge 86+，它们支持 File System Access API，可以流式写入任意大小的文件。

内存压力

即使使用流式写入，以下因素仍会消耗内存：

• 并发下载的分片数据（每个分片通常 1-10MB）
• FFmpeg WASM 运行时内存（约 200-400MB）
• 页面 UI 和其他组件

建议：

• 下载超大文件（>5GB）时，将并发线程数降至 1-2
• 关闭其他占用内存的标签页
• 避免同时运行多个 FFmpeg 转封装任务

流媒体协议限制

DRM 保护内容

FlowPick 无法处理以下类型的受保护内容：

检测方式：DASH 清单中出现 <ContentProtection> 标签时，下载器会明确提示不支持。

为什么无法支持 DRM？

DRM 系统的核心是内容解密模块（CDM），它是浏览器内置的闭源二进制组件。CDM 与操作系统和硬件深度绑定，负责解密受保护的内容并将解码后的帧直接输出到显卡，应用层无法拦截或读取解密后的数据。这是 DRM 系统的设计目标——确保内容在从解密到显示的整个链路中不被截获。

AES-128 加密

FlowPick 支持 HLS 的 AES-128 分片加密，但有以下限制：

• 仅支持 METHOD=AES-128，不支持 SAMPLE-AES
• 密钥文件必须可通过 HTTP(S) 直接访问
• 不支持需要 Cookie 认证的密钥 URL（在线工具模式）

直播流

FlowPick 主要面向点播（VOD）内容设计：

• 直播 HLS 流可以下载已缓存的分片，但无法获取未来的分片
• 直播流的分片列表会持续更新，下载器不会自动追踪新增分片
• 建议等待直播结束后再下载完整回放

直播流下载的实际效果：

直播进行中（已播放 30 分钟）：
  M3U8 清单包含最近 ~30 秒的分片
  → 下载器只能获取这 30 秒的内容
  → 无法获取之前或之后的分片

直播结束后：
  M3U8 清单包含完整分片列表
  → 下载器可以获取全部内容
  → 等同于点播下载

分离音视频流

部分 DASH 流将视频和音频分离为独立的 AdaptationSet：

• 下载器会分别列出视频流和音频流
• 需要手动选择匹配的视频和音频流
• 合并需要 FFmpeg WASM，耗时较长
• 如果音视频时长不一致，合并结果可能出现音画不同步

浏览器限制

File System Access API

在不支持的浏览器中，所有下载使用 Blob 模式，受 1.5GB 大小限制。

SharedArrayBuffer

FFmpeg WASM 多线程模式需要 SharedArrayBuffer，这要求网站设置以下 HTTP 响应头：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

如果这些头未设置，FFmpeg 自动降级为单线程模式，合并速度降低约 40-60%。

Service Worker

StreamSaver.js 依赖 Service Worker。以下情况会导致 StreamSaver 不可用：

• 浏览器隐私模式（部分浏览器限制 Service Worker）
• 企业策略禁用 Service Worker
• 网站未正确部署 mitm.html 和 streamsaver-sw.js

网络限制

CORS 跨域限制

在线工具模式（/m3u8-downloader、/dash-downloader）受浏览器同源策略限制：

• 如果流媒体服务器未设置 Access-Control-Allow-Origin 响应头，请求会被阻止
• 部分 CDN 会检查 Referer 或 Origin 请求头
• 扩展版本不受此限制，因为它使用扩展权限发起请求

CORS 错误的技术原理：

在线工具（flowpick.app）请求 CDN（cdn.example.com）：

浏览器发送请求 → CDN 返回分片数据
                      ↓
              浏览器检查响应头：
              Access-Control-Allow-Origin 是否包含 flowpick.app？
                      ↓
              否 → 浏览器阻止 JavaScript 读取响应
              是 → 正常读取

扩展版本：
扩展通过 chrome.webRequest / chrome.fetch 发起请求
→ 不受同源策略限制
→ 可以读取任何来源的响应

请求频率限制

部分 CDN 会对高频请求进行限流：

• 并发线程数过高可能触发 429（Too Many Requests）错误
• 建议将并发数控制在 4 以内
• 如果遇到限流，降低并发数后重试

分片 URL 过期

部分流媒体服务的分片 URL 包含时效性令牌：

• 令牌过期后分片无法下载
• 过期时间通常为几分钟到几小时
• 建议在获取清单后尽快开始下载
• 如果下载中断时间过长，可能需要重新获取清单

典型过期场景：

格式转换限制

FFmpeg WASM 性能

FFmpeg 在浏览器中以 WebAssembly 运行，性能远低于原生版本：

性能差异的原因：

1. WASM 执行开销：WebAssembly 在浏览器沙箱中运行，指令执行效率约为原生的 70-80%
2. SIMD 限制：FFmpeg 大量使用 SIMD 指令优化，WASM SIMD 支持不如原生完善
3. 内存访问：WASM 线性内存模型与原生内存管理有差异
4. I/O 瓶颈：虚拟文件系统的读写速度远低于原生文件系统

不支持的转换

以下转换路径当前不支持：

• 任意格式 → AVI、MOV、MKV、WebM
• 视频编码转换（如 H.264 → H.265）
• 音频编码转换（如 AAC → MP3）
• 分辨率缩放
• 添加水印或字幕

FlowPick 的 FFmpeg 集成专注于容器格式转换（转封装），不涉及编解码。

转封装 vs 转码：

转封装（FlowPick 支持）：
  TS 容器 → 提取 H.264 视频流 + AAC 音频流 → 封装为 MP4 容器
  特点：不改变编码，速度快，无损

转码（FlowPick 不支持）：
  H.264 视频流 → 解码 → 重新编码为 H.265 → 封装
  特点：改变编码，速度慢，有损，CPU 密集

扩展版本限制

Manifest V3 限制

FlowPick 扩展使用 Chrome Manifest V3，存在以下平台限制：

• Service Worker 生命周期受限（空闲约 30 秒后终止）
• 无法使用持久化后台页面
• 网络请求监听依赖 webRequest API

Manifest V3 对 FlowPick 的影响：

检测范围

扩展的媒体检测依赖于网络请求监控：

• 只能检测扩展激活后发起的请求
• 页面刷新后可以重新检测
• 某些使用 WebSocket 或 MSE 的网站可能检测不到媒体 URL
• iframe 中的媒体可能无法检测（取决于 iframe 的跨域策略）

已知 Bug

大文件 Blob 下载可能卡住

症状：使用 Blob 模式下载接近 1.5GB 的文件时，浏览器可能长时间无响应。

原因：new Blob([...]) 构造时需要复制所有数据，大文件的内存分配和复制耗时较长。

临时方案：使用 Chrome 浏览器以启用流式写入。

FFmpeg 首次加载较慢

症状：首次使用格式转换功能时，FFmpeg 加载需要 10-30 秒。

原因：FFmpeg WASM 核心文件（约 8MB）需要从网络下载并编译。

说明：这是正常现象，后续使用会利用浏览器缓存，加载速度显著提升。

加载时间分解：

首次加载：
  下载 WASM 文件（~8MB）  →  2-5 秒（取决于网速）
  WASM 编译               →  5-15 秒（取决于 CPU）
  初始化虚拟文件系统       →  1-3 秒
  总计                    →  10-30 秒

后续加载（缓存命中）：
  从缓存读取 WASM          →  <1 秒
  WASM 编译（可能缓存）    →  1-3 秒
  总计                    →  2-5 秒

部分 CDN 分片下载偶发失败

症状：下载过程中个别分片返回 503 或网络错误。

原因：CDN 节点临时故障或网络波动。

说明：FlowPick 内置了 3 次重试机制（指数退避），通常可以自动恢复。如果所有重试均失败，该分片会被跳过并在日志中记录。

相关文档

• 常见问题排查 — 按症状分类的诊断步骤和解决方案
• 常见问题解答 — 高频问题与简明解答
• 下载引擎架构 — 下载引擎的完整技术架构
• 视频嗅探 — HLS/DASH 清单解析与加密检测
• 格式转换 — FFmpeg WASM 引擎与输出格式
• 批量下载 — 队列调度与并发控制
• 浏览器兼容性 — 各浏览器 API 支持与降级策略
• 在线工具 — 在线工具的使用与限制
• 隐私与安全 — 权限说明与隐私保护
• 配置参考 — 并发数、过滤等配置项
• 安装指南 — 扩展安装与激活
• 直播回放保存 — 超大文件下载场景
• 贡献指南 — 如何报告 Bug 和贡献代码