贡献指南

如何为 FlowPick 项目贡献代码、文档或反馈问题。

感谢你对 FlowPick 项目的关注。本文档将指导你如何参与项目贡献，包括代码提交、文档改进和问题反馈。

行为准则

参与本项目即表示你同意遵守以下基本原则：

  • 使用友好和包容的语言
  • 尊重不同的观点和经验
  • 建设性地接受批评
  • 关注对社区最有利的事情
  • 对其他社区成员表现出同理心

贡献方式

报告 Bug

如果你发现了 Bug，请通过 GitHub Issues 提交报告。一个好的 Bug 报告应包含：

标题：简洁描述问题

描述：
- 预期行为是什么？
- 实际发生了什么？

复现步骤：
1. 打开 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 观察到错误

环境信息：
- 操作系统：Windows 11 / macOS 14 / Ubuntu 24.04
- 浏览器：Chrome 125 / Edge 125
- FlowPick 版本：v1.0.0
- 扩展版本还是在线工具？

附加信息：
- 控制台错误日志
- 截图或录屏
- 相关的流媒体 URL（如果可公开访问）
提交 Bug 前，建议先在 Console 中运行 诊断报告生成器，将输出一并附上。同时请查阅 已知问题 确认是否为已记录的已知限制。

功能请求

提交功能请求时，请说明：

  • 你的使用场景是什么？
  • 这个功能解决什么问题？
  • 你期望的行为是什么？
  • 是否有替代方案？
在提交功能请求前，建议先了解 FlowPick 的 技术架构 和 已知限制，确保你的需求在技术上是可行的。

改进文档

文档改进是最容易参与的贡献方式：

  1. 找到需要改进的文档页面
  2. 点击页面底部的"编辑此页"链接（如果可用）
  3. 直接在 GitHub 上编辑并提交 Pull Request

或者：

  1. Fork 仓库
  2. 在 content/ 目录下找到对应的 Markdown 文件
  3. 修改后提交 Pull Request

文档改进的常见方向：

方向说明参考
修正错误技术描述不准确、配置示例有误对照 项目架构 验证
补充细节某个功能缺少使用说明或参数解释参考 功能文档 的风格
添加示例缺少实际使用场景的代码或操作示例参考 使用场景 的写法
翻译将文档翻译为其他语言参考 多语言 章节
修复链接交叉引用链接失效或指向错误检查 ::note 块中的链接

贡献代码

如果你想贡献代码，请遵循以下流程。

开发环境搭建

前置要求

工具最低版本说明
Node.js18.x推荐使用 nvm 或 fnm 管理版本
pnpm8.x包管理器
Git2.x版本控制

克隆与安装

git clone https://github.com/ezwebtools/flowpick.git
cd flowpick-web
pnpm install

启动开发服务器

pnpm dev

开发服务器默认运行在 http://localhost:3000。

如果你需要测试 FFmpeg WASM 多线程模式，请确保开发服务器配置了正确的 COEP/COOP 响应头。详见 浏览器兼容性 — 高级 API。

项目结构

flowpick-web/
├── app/                    # 应用源码
│   ├── assets/             # 静态资源（CSS）
│   ├── components/         # Vue 组件
│   │   └── content/        # Nuxt Content 专用组件
│   ├── composables/        # 组合式函数
│   │   ├── useFFmpeg.ts    # FFmpeg WASM 集成
│   │   ├── useStreamMerge.ts # 流合并与下载引擎
│   │   ├── useClarity.ts   # Microsoft Clarity 分析
│   │   └── useGA4.ts       # Google Analytics
│   ├── layouts/            # 布局组件
│   ├── pages/              # 页面路由
│   │   ├── docs/           # 文档页面
│   │   ├── changelog/      # 更新日志页面
│   │   ├── legal/          # 法律页面
│   │   ├── m3u8-downloader.vue  # M3U8 下载器
│   │   ├── dash-downloader.vue  # DASH 下载器
│   │   └── index.vue       # 首页
│   ├── types/              # TypeScript 类型声明
│   ├── app.config.ts       # 应用配置
│   └── app.vue             # 根组件
├── content/                # Nuxt Content 文档
│   └── zh-Hans/            # 简体中文文档
├── public/                 # 公共静态资源
│   ├── ffmpeg/             # FFmpeg WASM 核心文件
│   └── ffmpeg-mt/          # FFmpeg WASM 多线程核心文件
├── nuxt.config.ts          # Nuxt 配置
├── package.json            # 项目依赖
└── tsconfig.json           # TypeScript 配置
关于各模块的详细职责、数据流和设计决策，请参阅 项目架构。关于下载引擎的完整技术实现，请参阅 下载引擎架构。

技术栈

技术用途
Nuxt 4全栈框架
Vue 3UI 框架
Nuxt UI v4组件库
Nuxt Content v3文档系统
Tailwind CSS v4样式
TypeScript类型安全
@ffmpeg/ffmpeg浏览器端媒体处理
m3u8-parserHLS 清单解析
mpd-parserDASH 清单解析
streamsaver流式文件保存

开发规范

代码风格

项目使用 ESLint 进行代码检查：

pnpm lint

类型检查

pnpm typecheck

提交前请确保类型检查通过。

提交信息规范

使用约定式提交（Conventional Commits）格式：

<type>(<scope>): <description>

[optional body]

[optional footer]

类型（type）：

类型说明
feat新功能
fixBug 修复
docs文档更新
style代码格式（不影响功能）
refactor代码重构
perf性能优化
test测试相关
chore构建/工具变更

示例：

feat(downloader): add concurrent segment download with configurable threads

Implemented a worker pool pattern for parallel segment downloading.
The concurrency level can be configured between 1-8 threads.

Closes #42

分支策略

  • main：稳定版本，随时可部署
  • develop：开发分支
  • feat/xxx：功能分支
  • fix/xxx：修复分支
  • docs/xxx：文档分支

Pull Request 流程

  1. Fork 仓库并创建功能分支
  2. 进行开发，确保代码通过 lint 和 typecheck
  3. 提交 PR 到 develop 分支
  4. PR 描述中说明改动内容和原因
  5. 等待代码审查

PR 审查关注点：

关注点说明
功能正确性改动是否实现了预期功能，边界情况是否处理
代码质量是否遵循现有代码风格，是否有重复代码
性能影响是否引入不必要的开销，大文件场景是否考虑
兼容性是否影响现有功能，浏览器兼容性是否考虑
安全性是否引入安全风险，用户数据是否得到保护
关于下载引擎的性能考量（并发控制、内存管理、重试策略），请参阅 下载引擎架构。关于浏览器兼容性的注意事项，请参阅 浏览器兼容性。

文档编写指南

文档结构

文档使用 Nuxt Content v3，以 Markdown 文件形式存放在 content/zh-Hans/ 目录下。

Frontmatter

每个文档文件需要包含以下 frontmatter：

---
title: 文档标题
description: 文档描述（用于 SEO 和列表展示）
navigation:
  icon: i-lucide-xxx  # Lucide 图标名称
---

内容格式

  • 使用 Markdown 标准语法
  • 代码块指定语言以获得语法高亮
  • 表格用于对比和参考信息
  • 使用 ::tip、::note、::warning 等 Nuxt Content 指令

导航配置

每个文档目录需要一个 .navigation.yml 文件：

title: 分类名称
icon: i-lucide-xxx

多语言

目前文档以简体中文（zh-Hans）为主。如果需要添加其他语言：

  1. 在 content/ 下创建对应语言目录（如 en/）
  2. 复制文档结构并翻译内容
  3. 保持文件路径和命名一致

测试

手动测试清单

提交涉及下载功能的 PR 前，请验证以下场景：

  • 小文件下载（<10MB）
  • 大文件下载（>500MB）
  • 加密 HLS 流下载
  • DASH 流下载
  • 格式转换（TS → MP4）
  • 并发线程数切换
  • 下载取消与重试
  • Chrome 浏览器
  • Edge 浏览器

各测试场景的验证要点：

测试场景验证要点参考文档
小文件下载下载完整性、速度显示、进度条下载引擎架构
大文件下载内存占用、流式写入、无崩溃下载引擎架构 — 内存安全管理
加密 HLSAES-128 解密、密钥获取视频嗅探 — 加密流
DASH 流音视频分离、FMP4 重组下载引擎架构 — DASH 流的特殊处理
格式转换FFmpeg 加载、转封装正确性格式转换 — FFmpeg WASM 引擎
并发切换线程数变化、速度对比配置参考
取消与重试AbortController、重试次数下载引擎架构 — 重试机制
浏览器兼容Chrome/Edge 功能一致性浏览器兼容性

测试用流媒体 URL

以下是一些可用于测试的公开流：

# 基础 HLS（无加密）
https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8

# 多画质 HLS
https://test-streams.mux.dev/pts_shift/pts_shift.m3u8

# 基础 DASH
https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd
关于 HLS 和 DASH 流的检测原理和清单结构，请参阅 视频嗅探。关于在线工具中如何使用这些测试 URL，请参阅 在线工具。

发布流程

  1. 在 develop 分支完成开发和测试
  2. 更新 content/zh-Hans/4.changelog/ 中的更新日志
  3. 合并 develop 到 main
  4. 创建版本标签（如 v1.1.0）
  5. 构建扩展包并提交到 Chrome Web Store

相关文档

视频直链下载失败怎么办？MP4、WebM 排查

排查视频直链返回 403、404、CORS、空文件、格式不支持、无法断点续传等问题，附带 curl 诊断代码。

项目架构

FlowPick 的技术架构详解，包括系统设计、模块划分、数据流和关键设计决策。