常见问题排查

本文档汇总了 FlowPick 使用过程中可能遇到的各类问题，按症状分类提供诊断步骤和解决方案。

问题快速索引

如果你已经知道问题类型，可以直接跳转到对应章节：

诊断工具与技巧

在深入排查之前，掌握以下诊断工具可以大幅提高效率。

浏览器开发者工具

按 F12 或 Ctrl+Shift+I 打开开发者工具，重点关注以下面板：

常见错误信息速查

在 Console 中看到以下错误时，可快速定位问题：

生成诊断报告

在遇到复杂问题时，可以在 Console 中运行以下代码生成诊断报告，方便提交 Issue：

// FlowPick 诊断报告生成器
const report = {
  userAgent: navigator.userAgent,
  platform: navigator.platform,
  language: navigator.language,
  fsaAvailable: 'showDirectoryPicker' in window,
  fsaSaveAvailable: 'showSaveFilePicker' in window,
  sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
  crossOriginIsolated: self.crossOriginIsolated,
  serviceWorker: 'serviceWorker' in navigator,
  storage: {
    quota: await navigator.storage?.estimate().catch(() => null),
  },
  timestamp: new Date().toISOString(),
}
console.log('FlowPick 诊断报告:', JSON.stringify(report, null, 2))

媒体检测问题

扩展无法检测到任何媒体

症状：打开包含视频/音频的网页后，点击 FlowPick 图标，弹出窗口显示"未检测到媒体资源"。

诊断步骤：

1. 确认页面已加载媒体
   在打开 FlowPick 之前，先让视频或音频播放几秒钟。许多网站采用懒加载策略，只有用户交互后才开始加载媒体流。
2. 刷新页面后重试
   扩展的媒体检测依赖于网络请求监控。如果扩展在页面加载之后才安装或激活，可能错过初始请求。刷新页面可以触发新的网络请求。
3. 检查扩展是否已激活
   点击扩展图标时，确认弹出窗口正常显示。如果弹出窗口无法打开，可能是扩展未正确安装或已被禁用。
4. 检查页面是否使用非标准协议
   部分网站使用 WebSocket、WebRTC 或自定义加密协议传输媒体，这些不在 FlowPick 的检测范围内。

常见原因与解决方案：

部分媒体未被检测到

症状：FlowPick 检测到了一些资源，但缺少某些预期的视频或音频。

可能原因：

• 动态加载时机：某些媒体在用户滚动或点击后才加载。尝试与页面交互后再打开 FlowPick
• 过滤设置：检查是否设置了最小文件大小过滤，导致小文件被排除。关于过滤配置，请参阅 配置参考 — 过滤设置
• MIME 类型不标准：服务器返回的 Content-Type 不在 FlowPick 的识别列表中。FlowPick 目前识别 25+ 种 MIME 类型，但某些 CDN 可能使用非标准类型

图片检测不完整

症状：页面上的图片没有全部出现在检测结果中。

原因分析：

• CSS background-image 中的图片需要页面完全渲染后才能被检测
• 懒加载图片（loading="lazy"）需要滚动到视口内才会加载
• 通过 JavaScript 动态创建的 <img> 元素可能在扩展扫描之后才插入 DOM
• Canvas 绘制的图片内容无法通过 DOM 检测获取

建议：滚动浏览整个页面后再打开 FlowPick，确保所有懒加载内容已被触发。

下载问题

下载无法开始

症状：点击下载按钮后没有反应，或立即显示错误。

诊断步骤：

1. 检查浏览器下载设置
   确认浏览器没有阻止自动下载。在 Chrome 中：设置 → 隐私与安全 → 网站设置 → 自动下载。
2. 检查磁盘空间
   确保系统磁盘有足够的可用空间。视频文件可能很大（数 GB），下载前请确认空间充足。
3. 检查是否有其他下载扩展冲突
   某些下载管理扩展可能拦截或修改下载请求。尝试暂时禁用其他下载相关扩展。
4. 检查浏览器控制台错误
   按 F12 打开开发者工具，查看 Console 面板中的错误信息。常见错误包括：
   • Failed to fetch：网络请求失败
   • CORS error：跨域请求被阻止
   • QuotaExceededError：存储空间不足

下载速度慢

症状：下载进度缓慢，速度远低于网络带宽。

影响因素与优化建议：

诊断流程：

下载速度慢
    │
    ├── 并发数 < 4？
    │   └── 是 → 增加并发数到 4-6，观察速度变化
    │
    ├── 速度波动大？
    │   └── 是 → 可能是 CDN 限速，尝试降低并发数到 2-3
    │
    ├── 所有下载都慢？
    │   └── 是 → 检查网络带宽，关闭其他占用带宽的应用
    │
    └── 仅特定网站慢？
        └── 是 → 该网站的 CDN 可能限速，尝试不同画质

下载中途失败

症状：下载进行到一定比例后报错停止。

常见错误及处理：

HTTP 403 Forbidden

分片 URL 可能包含时效性 token，过期后服务器拒绝访问。解决方案：

• 刷新页面获取新的流地址
• 尽快完成下载，避免 token 过期
• 对于 HLS 流，token 通常在 M3U8 清单中，重新获取清单即可

HTTP 404 Not Found

分片已被服务器删除（常见于直播回放）。解决方案：

• 确认流是否仍然可用
• 尝试选择不同的画质（不同画质可能使用不同的分片文件）

网络连接中断

自动重试机制会处理临时网络波动。如果持续失败：

• 检查网络连接稳定性
• 降低并发线程数，减少同时进行的连接
• 检查防火墙或代理设置

CORS 错误

在线工具版本受浏览器同源策略限制。解决方案：

• 使用浏览器扩展版本（扩展有更宽松的网络权限）
• 如果使用在线工具，确认流 URL 的服务器允许跨域请求

下载的文件无法播放

症状：下载完成，但视频/音频文件无法在播放器中打开。

诊断与修复：

1. 尝试不同的播放器
   某些播放器对特定编码或容器的支持有限。推荐使用以下播放器测试：
   • VLC Media Player（兼容性最好）
   • MPC-HC
   • PotPlayer
2. 检查文件大小
   如果文件大小明显小于预期（例如只有几 KB），可能是下载了 M3U8 清单文件而非实际视频。确认选择了正确的资源。
3. 尝试不同的画质
   某些画质的分片可能存在编码问题。尝试下载较低或较高的画质版本。
4. 使用 VLC 的修复功能
   VLC 提供内置的 AVI/MP4 修复功能：
   • 打开 VLC → 媒体 → 转换/保存
   • 添加文件 → 转换/保存
   • 选择输出格式 → 开始
5. 检查合并是否完整
   如果下载过程中浏览器崩溃或网络中断，合并可能不完整。重新下载通常可以解决。

大文件下载失败

症状：下载大文件（>1GB）时浏览器卡顿或崩溃。

原因：Blob 模式下，整个文件需要加载到内存中才能触发下载。对于超大文件，这可能导致内存不足。

解决方案：

• 使用 File System Access API 的保存目录功能，文件直接写入磁盘，不占用内存
• 如果浏览器不支持 FSA API，FlowPick 会自动使用 StreamSaver.js 流式写入
• 如果两种流式写入都不可用，Blob 模式有 1.5GB 的硬限制，超过此大小的文件会被拒绝

合并问题

合并后的视频音画不同步

症状：视频和音频轨道存在时间偏移。

原因：这通常发生在 DASH 流中，视频和音频分片的时间戳不完全对齐。FlowPick 使用 -c copy 模式合并，不做重新编码，因此无法修正时间戳偏移。

解决方案：

• 尝试选择不同的画质（不同画质的音视频同步可能不同）
• 使用 FFmpeg 命令行工具手动重新编码：

ffmpeg -i output.mp4 -c:v libx264 -c:a aac -async 1 fixed.mp4

合并过程卡住

症状：进度条长时间停留在"合并中"阶段。

原因分析：

• FFmpeg WASM 在处理大量分片时需要较长时间
• 多线程模式下 SharedArrayBuffer 不可用时，FFmpeg 回退到单线程，速度显著降低
• 内存不足导致 WASM 运行缓慢

建议：

• 等待合并完成，大文件的合并可能需要数分钟
• 选择 TS 输出格式可以跳过 FFmpeg 转码，直接二进制拼接（秒级完成）
• 关闭其他占用内存的标签页

浏览器兼容性问题

SharedArrayBuffer 不可用

症状：控制台显示 SharedArrayBuffer is not defined 或 FFmpeg 运行在单线程模式。

原因：SharedArrayBuffer 需要页面设置正确的安全头。FlowPick 网站已配置：

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

如果你的部署环境没有这些头，FFmpeg 会自动回退到单线程模式，功能不受影响但速度较慢。

File System Access API 不可用

症状：没有"选择保存目录"按钮，或点击后无反应。

支持情况：

在不支持的浏览器上，FlowPick 自动使用浏览器默认下载方式。

StreamSaver.js 不工作

症状：控制台显示 StreamSaver 相关错误。

可能原因：

• Service Worker 注册失败（某些浏览器策略禁止）
• mitm.html 页面无法加载
• 浏览器不支持 WritableStream

FlowPick 会自动降级到 Blob 模式，功能不受影响。

扩展特定问题

扩展图标不显示

1. 点击浏览器工具栏的拼图图标（扩展管理）
2. 找到 FlowPick
3. 点击图钉图标将其固定到工具栏

扩展被自动禁用

Chrome 可能会在以下情况禁用扩展：

• 扩展更新后需要新权限
• 浏览器检测到可疑行为
• 开发者模式扩展在浏览器重启后被禁用

解决方案：在 chrome://extensions 页面重新启用 FlowPick。

快捷键冲突

默认快捷键 Alt+Shift+F 和 Alt+Shift+D 可能与其他扩展或系统快捷键冲突。

修改方法：

1. 打开 chrome://extensions/shortcuts
2. 找到 FlowPick
3. 设置新的快捷键组合

网络问题排查

代理/VPN 环境

如果你在使用代理或 VPN，下载可能受到影响：

企业网络环境

企业网络通常有更严格的安全策略，可能导致以下问题：

• 防火墙阻止非标准端口：部分流媒体使用非 80/443 端口，可能被企业防火墙阻止
• Service Worker 被禁用：某些企业管理策略禁止 Service Worker，导致 StreamSaver.js 不可用
• 扩展安装受限：企业管理的浏览器可能禁止安装非白名单扩展

建议：在企业网络环境中，优先使用在线工具版本（如果可访问），或联系 IT 部门了解网络策略。

获取帮助

如果以上方案无法解决你的问题：

1. 检查 GitHub Issues 是否有类似问题
2. 提交新的 Issue，附上以下信息：
   • 浏览器及版本
   • FlowPick 版本
   • 问题描述和复现步骤
   • 浏览器控制台的错误日志（F12 → Console）
   • 问题页面的 URL（如果可公开访问）
   • 诊断报告 的输出内容

相关文档

• 已知问题 — 当前版本的技术限制和边界情况
• 常见问题解答 — 高频问题与简明解答
• 下载引擎架构 — 下载引擎的完整技术架构
• 视频嗅探 — 媒体检测的技术原理
• 格式转换 — FFmpeg WASM 引擎与输出格式
• 批量下载 — 队列调度与并发控制
• 浏览器兼容性 — 各浏览器 API 支持与降级策略
• 在线工具 — 在线工具的使用与限制
• 隐私与安全 — 权限说明与隐私保护
• 配置参考 — 并发数、过滤等配置项
• 安装指南 — 扩展安装与激活
• 键盘快捷键 — 快捷键配置与冲突解决
• 图片下载 — 图片检测与下载功能
• 贡献指南 — 如何报告 Bug 和贡献代码
• 直播回放保存 — 超大文件下载场景
• 图库批量保存 — 图片批量下载场景

专题故障排查

• M3U8 下载失败
• DASH 视频没有声音
• 视频直链下载失败