企业官网建设流程全解析

• 前端
• 音视频
• WebRTC

Magnet Player 是一个完全运行在浏览器中的种子流媒体站点：粘贴一条 magnet 链接（或种子文件 URL、info hash），即可直接开始播放视频，无需安装任何插件、扩展或客户端软件。本指南以仓库的 about.md 为核心，结合 js/webtorrent.js、index.html 等源码，完整讲解其基于 WebTorrent 与 WebRTC 的实现原理、"并非所有种子都能播放"这一关键限制背后的原因，以及当前 WebTorrent 生态的兼容现状，帮助你理解这类浏览器 P2P 流媒体方案的适用边界。

项目定位：浏览器即客户端

Magnet Player 的官方定位（见 about.md）是一句话可以概括的：

Magnet Playeris a site where anyone can stream torrents directly from their browser.

翻译过来就是：任何访客都可以直接在浏览器里流式播放种子内容。它的实现基础是WebTorrent——第一个能在浏览器中运行的 torrent 客户端；而 WebTorrent 使用WebRTC作为真正的点对点传输通道。因此整个过程不需要浏览器插件、扩展或任何安装步骤。

这个"零安装"承诺在页面交互上体现得很直接。index.html 的首页就是一个表单：输入框的placeholder是magnet:，提交按钮只有一个Play。用户能粘贴进输入框的内容类型，在页面下方被明确列出：

• magnet uri（字符串）
• torrent file（buffer）
• info hash（十六进制字符串或 buffer）
• parsed torrent（来自 parse-torrent 的解析结果）
• http/https url 指向的 torrent 文件（字符串）

也就是说，无论你手头是 magnet 链接、info hash 还是 .torrent 文件的 URL，都能作为 WebTorrent 的torrentId直接交给客户端解析——这一点从 index.html 的<input id="torrentId" name="torrentId">到 js/webtorrent.js 的提交处理逻辑是一一对应的。

核心传输原理：为什么用 WebRTC 而不是 TCP/uTP

传统 torrent 客户端（如 BitTorrent、Transmission、μTorrent）走的是TCP或uTP传输协议，这要求本机能开放并监听对应的网络端口。而浏览器出于安全沙箱的限制，既不能监听 TCP/UDP 端口，也无法建立原始 socket 连接——这正是 WebTorrent 选择 WebRTC 的根本原因。

WebRTC 提供两样浏览器原生支持的能力：

1. 真正的点对点（P2P）传输：通过 DTLS/SRTP 加密的数据通道直接在两个浏览器之间传输数据，无需经过服务器中转。
2. 浏览器内建的 UDP 打洞（NAT traversal）：借助 STUN/ICE 机制穿越 NAT 和防火墙，让两个内网浏览器也能建立直连。

与此同时，tracker 通信也必须适配浏览器环境：经典 tracker 使用 UDP/TCP 协议，浏览器无法直接访问，因此必须使用基于 WebSocket 的 tracker。这一点在源码中有明确印证——js/webtorrent.js 第 25-36 行定义了一个announceList，其中既包含 UDP tracker 也包含 WSS tracker：

const announceList = [ ['udp://tracker.openbittorrent.com:80'], ['udp://tracker.opentrackr.org:1337'], ['wss://tracker.openwebtorrent.com'], ['wss://tracker.webtorrent.dev'], ['wss://tracker.files.fm:7073/announce'], ['wss://tracker.novage.com.ua'], ] window.WEBTORRENT_ANNOUNCE = announceList .map(arr => arr[0]) .filter(url => url.startsWith('wss://') || url.startsWith('ws://'))

注意最后一步：交给 WebTorrent 客户端的全局 announce 列表只保留wss:///ws://的 tracker。这是因为浏览器环境下 UDP tracker 不可达，只有 WebSocket tracker 才能真正被客户端用来寻找 peer。这与项目描述（"Stream torrents directly from your browser using WebTorrent"）完全一致。

从粘贴链接到视频播放：一次完整的调用链

Magnet Player 的播放流程在 js/webtorrent.js 中清晰可见，大致分四步：

第一步：注册 Service Worker，准备流媒体服务

file.streamTo()这类浏览器流媒体接口依赖 Service Worker 来代理媒体请求，因此代码在页面加载后先注册并等待 worker 完全激活（activated状态），然后调用client.createServer({ controller })，并把ready置为true，之后才允许用户输入（js/webtorrent.js）。仓库根目录的 sw.min.js 正是这个 Service Worker：它会拦截所有以webtorrent/为前缀的请求，通过与页面主线程的MessageChannel通信来转发数据流——这就是"浏览器内播放种子视频"的底层机制。如果注册失败，输入框占位符会变成Error: streaming not supported in this browser，明确提示当前浏览器不支持该特性。

第二步：接收 torrentId 并加入下载

表单提交（js/webtorrent.js）或 URL hash 变化（onHashChange，js/webtorrent.js）都会触发downloadTorrent(torrentId)，最终调用：

const torrent = client.add(torrentId, onTorrent)

client.add()是 WebTorrent 客户端的核心入口，接受上文列举的所有torrentId形态。同时代码启动了一个每秒一次的定时器：如果 30 秒内既没有找到 peer 也没有下载完成，就把加载状态改为 "No peers found after 30s. Only torrents with WebRTC seeders are supported in the browser."（js/webtorrent.js）——这句话就是 about.md 中 "Note" 的运行时体现。

第三步：自动挑选并播放文件

onTorrent回调（js/webtorrent.js）做三件事：

1. 更新分享链接：把#${torrent.infoHash}写进 URL，方便把当前视频分享给别人（对方打开同一链接即可加入）；
2. 隐藏输入表单；
3. 找到体积最大的文件并立即playFile()，实现"粘贴即播放"。

playFile()（js/webtorrent.js）动态创建一个带controls与autoplay的<video>元素，然后调用 WebTorrent 的文件流式接口：

file.streamTo(video)

streamTo()会把 torrent 文件按需（on-demand）拉取的数据通过前面创建的 Service Worker 以 HTTP 流喂给<video>，于是视频可以在尚未下载完整文件时就开始播放——这正是"流媒体"而非"先下载后观看"的关键。

第四步：实时统计展示

setInterval(onProgress, 500)每 500ms 刷新一次统计区（js/webtorrent.js）：peer 数量、下载/上传速度、已下载字节数、总大小、剩余时间以及进度条宽度。下载完成后页面进入is-seed状态（torrent.on('done', onDone)），此时当前浏览器也成为了一个 WebRTC seeder，继续为其他 peer 提供上传。如果种子包含多个文件，页面还会弹出文件选择器，按文件大小降序排列供用户切换播放（js/webtorrent.js）。

关键限制：为什么"不是所有种子都能播放"

这是 about.md 中最核心的提示（Note 部分），完整继承如下：

In the browser, WebTorrent can only download torrents that are seeded by a WebRTC-capable torrent client.

这意味着什么？目前，并不是每个种子都能在这个网站上播放。

为什么？因为绝大多数人使用的原生 torrent 客户端——BitTorrent、Transmission、μTorrent 等——并不使用 WebRTC 传输协议，而是使用 TCP/uTP。它们与浏览器之间不存在通用的传输通道：

• 原生客户端之间：通过 TCP/uTP 直连，走传统 tracker（UDP/TCP）；
• 浏览器之间：通过 WebRTC 数据通道互连，走 WebSocket tracker。

两个生态是割裂的：WebTorrent 浏览器客户端只能和同样具备 WebRTC 能力的 seeder 互通。因此，如果一个种子的所有做种者都是传统原生客户端，那么浏览器里的 WebTorrent 客户端就找不到任何可连接的 peer，播放自然无法开始。

这条限制在源码中处处可见：上文提到的 tracker 过滤逻辑、30 秒无 peer 的提示文案，以及 js/webtorrent.min.js（仓库内置的 WebTorrent v2.8.5 预构建浏览器包）只实现 WebRTC 传输层的事实，都是同一个结论的注解。

生态现状：哪些客户端已经支持 WebTorrent

好消息是：这个限制正在被逐步打破。about.md 明确指出，已经有多个 torrent 客户端开始支持 WebTorrent：

• Vuze：老牌 Java 桌面客户端，内置 WebTorrent 支持；
• Brave：内置 WebTorrent 的浏览器，可以直接播放 magnet 链接，同时也承担了 WebRTC seeder 的角色；
• 基于 libtorrent 构建的客户端：libtorrent 是 C++ 实现的流行 torrent 库，qBittorrent、Deluge 等知名客户端均基于它构建，相关 WebTorrent 支持正在演进。

也就是说，"浏览器能否播放某个种子"取决于做种方是否跑在 WebRTC 兼容客户端上。随着支持 WebTorrent 的客户端越来越多，能被浏览器直接流式播放的种子范围会持续扩大。关于这项能力的进展，可以持续关注 WebTorrent 官方仓库（webtorrent/webtorrent）中对应的 issue 讨论。

本地构建与运行方式

本仓库是一个 Jekyll 站点 + esbuild 打包的纯前端项目（package.json、CLAUDE.md），本地运行方式如下：

# 安装 Ruby 依赖（Jekyll 站点） bundle install # 安装 JS 依赖 npm install # 重新打包 JS（js/main.js -> js/bundle.js） npm run build # 本地启动站点 bundle exec jekyll serve

需要注意一个前置条件：Service Worker 只在 HTTPS（或 localhost 的部分场景）下可用，而种子视频流依赖 Service Worker，因此通过bundle exec jekyll serve在纯 HTTP 的 localhost 上预览时，页面能打开但流媒体播放可能不工作（这也是 CLAUDE.md 中明确记录的限制）。此外，JS 入口是 js/main.js（负责剪贴板分享等 UI 逻辑），它require('./webtorrent.js')并作为 esbuild 的打包入口；修改任何 JS 后都需要重新执行npm run build以刷新 js/bundle.js。站点本身的主题、SEO 等配置集中在 _config.yml。

小结

Magnet Player 用约两百行核心代码（js/webtorrent.js）加一个 Service Worker（sw.min.js），把"粘贴链接 → P2P 下载 → 边下边播"的完整链路搬进了浏览器。它的可行性建立在 WebTorrent + WebRTC 之上，而它的边界同样清晰：浏览器里只能播放由 WebRTC 兼容客户端做种的种子。理解这条边界，就能准确判断这类方案的适用场景——例如配合 Brave、Vuze 等 WebRTC 生态客户端使用，而不是期望它替代传统 BitTorrent 生态。对希望在自己的站点里集成"零安装流媒体播放"能力的开发者来说，本仓库的代码组织（表单输入、Service Worker 流服务、统计刷新、防 XSS 的textContent输出）就是一份可以直接参考的完整范本。

• 前端
• 音视频
• WebRTC