FlowPick 详细部署教程

1. 项目简介

FlowPick 是一个隐私优先的开源流媒体下载工具，支持 HLS（.m3u8）、DASH（.mpd）视频流、音频、图片的嗅探、下载、合并与转码。其核心特点是所有处理都在浏览器内通过 FFmpeg WASM 完成，文件不经过第三方服务器，确保用户隐私安全。

主要功能：

视频检测：支持常规网页视频和 HLS/M3U8 流媒体视频
音频提取：抓取网页中的音频文件，如背景音乐、播客
图片下载：自动扫描全页图片，支持批量打包下载
实时预览：可在列表内预览视频或图片
隐私安全：本地端处理，不收集用户数据

支持的格式：

流媒体：M3U8（HLS）、MPD（DASH）
视频：MP4、WebM、MKV、AVI、MOV、WMV、FLV 等
音频：MP3、M4A、WAV、FLAC、AAC、OGG 等
图像：JPG、PNG、WebP、GIF、SVG、BMP、ICO

FlowPick 提供两种使用形态：浏览器扩展和在线工具网站。本教程主要讲解在线工具网站的部署方法。

2. 部署前准备

2.1 环境要求

在开始部署之前，请确保你的系统满足以下要求：

Node.js：20 LTS 或更高版本
pnpm：包管理工具（仓库脚本默认使用 pnpm）
Git：用于克隆项目源码

验证环境：

1
2
3

node -v   # 应显示 v20.x 或更高
pnpm -v
git --version

2.2 获取源码

1 2	git clone https://github.com/ezwebtools/flowpick.git cd flowpick

2.3 安装依赖

1	pnpm install

注意事项：postinstall 脚本会自动运行 nuxt prepare，生成类型声明和路由清单。首次安装会稍微慢一些，如果安装被中断，可以手动运行 pnpm exec nuxt prepare 来补齐。

3. 本地开发运行

3.1 启动开发服务器

pnpm dev

打开浏览器访问 http://localhost:3000。

3.2 主要页面

/m3u8-downloader — HLS 流下载器
/dash-downloader — DASH 流下载器
/docs — 完整文档
/blog — 教程和深度文章

3.3 测试下载功能

HLS 下载示例：

打开一个提供 .m3u8 流的页面
按 F12 打开开发者工具 → Network → 筛选 m3u8
播放视频几秒钟，让 manifest 被请求
右键点击 .m3u8 请求 → 复制链接地址
粘贴到 M3U8 Downloader 中
点击 Parse，FlowPick 会读取 manifest 并列出可用画质
选择画质，点击 Start Download

FlowPick 会自动下载所有分片、解密（如需要 AES-128）、并合并文件。对于 MP4 输出，它会在浏览器内运行 remux 命令：

1	ffmpeg -i input.ts -c copy output.mp4

全程无需重新编码，画质无损，文件不经过服务器。

4. 生产环境部署

4.1 重要前提：必须保留的响应头

下载器页面（/m3u8-downloader、/dash-downloader）在 nuxt.config.ts 中配置了两个关键响应头：

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

这两个头用于开启 cross-origin isolation，直接影响：

FFmpeg WASM 能否运行多线程（依赖 SharedArrayBuffer）
大文件能否通过 StreamSaver 进行跨源流式写入

无论使用哪种部署方式，这两个响应头都不能丢失。

4.2 方案一：静态网站托管（推荐）

适合只需要一个稳定可访问的网页版的场景，零服务器运维。

步骤 1：改为静态预设并构建

编辑 nuxt.config.ts：

export default defineNuxtConfig({
  nitro: {
    preset: 'static'  // 改为静态预设
  }
})

执行构建：

1 2	pnpm build # 产物在 .output/public 目录

步骤 2：上传到静态托管平台

可以将 .output/public 目录上传到任意静态托管服务，如：

腾讯云 CloudBase 静态网站托管
Vercel
Netlify
GitHub Pages
自有服务器 + Nginx

步骤 3：绑定域名并开启 HTTPS

在托管平台设置中绑定你的域名，并开启 HTTPS。

步骤 4：补上 COOP/COEP 响应头

静态托管不会自动读取 Nuxt 的 routeRules，需要手动为下载器路由添加响应头。在托管平台的自定义响应头配置中添加：

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

验证配置是否生效：

1 2	curl -I https://你的域名/m3u8-downloader \| grep -i "cross-origin" # 应能看到 cross-origin-opener-policy 与 cross-origin-embedder-policy

提示：FFmpeg WASM 首次加载约 8MB，建议在 CDN/托管层开启缓存，弱网环境下首次加载会快很多。

4.3 方案二：Node 服务部署

适合需要服务端渲染、或已有服务器想统一管理的场景。

步骤 1：改为 Node 预设并构建

编辑 nuxt.config.ts：

export default defineNuxtConfig({
  nitro: {
    preset: 'node-server'
  }
})

执行构建：

1	pnpm build

步骤 2：启动服务

1 2	node .output/server/index.mjs # 默认监听 3000 端口

使用 Nitro 的 node-server 预设时，nuxt.config.ts 中的 routeRules 响应头会由服务端自动注入，下载器路由的 COOP/COEP 一般已经就位，无需 Nginx 再补充。

步骤 3：使用 PM2 守护进程

为避免服务意外退出，推荐使用 PM2 或 systemd 守护：

# 安装 PM2
npm install -g pm2

# 启动服务
pm2 start .output/server/index.mjs --name flowpick

# 设置开机自启
pm2 startup
pm2 save

5. 浏览器扩展安装（可选）

如果你只想使用 FlowPick 的扩展功能，可以从以下渠道安装：

Chrome：Chrome 应用商店搜索 “FlowPick”
Edge：Microsoft Edge 加载项搜索 “FlowPick: Media Sniffer & Downloader”
Firefox：addons.mozilla.org 搜索 “FlowPick”

扩展使用方法：

安装扩展后，打开目标视频的播放页面
点击浏览器右上角的 FlowPick 图标
扩展会列出当前页面嗅探到的所有媒体资源，按类型分组显示
选中想要的资源，可以先预览确认内容
点击 “Pick” 创建下载任务
m3u8 流会先并行下载切片，再在本地合并成 MP4

注意：下载过程中不要关闭显示任务的选项卡，任务完成后点击保存即可。

6. 常见问题与解决方案

6.1 FFmpeg WASM 无法运行

问题：下载功能报错，提示 SharedArrayBuffer 不可用。

解决方案：检查响应头配置，确保 COOP/COEP 两个头都已正确设置。

6.2 首次加载缓慢

问题：首次访问下载器页面时加载时间较长。

解决方案：FFmpeg WASM 首载约 8MB，这是正常现象。建议在 CDN 层开启缓存以加速后续访问。

6.3 安装依赖时中断

问题：pnpm install 过程中断，导致类型声明不完整。

解决方案：运行 pnpm exec nuxt prepare 补齐生成的类型声明和路由清单。

6.4 RTMP 流无法下载

问题：某些流媒体无法被检测到。

解决方案：FlowPick 基于浏览器的 webRequest API 工作，只能嗅探 HTTP 协议的资源。RTMP 不是 HTTP 协议，无法被检测。FlowPick 支持的是 HLS、DASH 和直链视频，这三类已覆盖绝大多数网页视频。

7. 部署架构总结

部署方式	适用场景	优势	注意事项
静态托管	只需网页版访问	零运维、成本低	需手动配置 COOP/COEP
Node 服务	需要 SSR 或已有服务器	响应头自动注入	需进程守护
浏览器扩展	个人使用	安装即用	需从商店安装

无论选择哪种方式，核心原则是确保 COOP/COEP 响应头正确配置，这是 FFmpeg WASM 多线程功能正常工作的前提。