Flutter番剧播放器Kazumi架构拆解：XPath规则与libmpv播放内核

别的写法一律抛异常。

if (!isIndex && !isWildcard && !isQuoted) {
  throw ApiRuleFormatException('不支持的 JSONPath 片段: [$content]');
}

为什么这么抠？因为完整的 JSONPath 支持过滤表达式，比如 $.data[?(@.type == 'tv')]。这一句在很多实现里会被当成一小段代码去求值。

而规则是别人写的、可以从外部导入的。一旦允许过滤表达式在本地跑，规则就不再是「配置」，而是「可以执行的逻辑」。这道门一开，后面就没底了。只放四种写法，够覆盖「取列表、取字段、取某个下标」这些真实需求，又把求值挡在外面。这不是限制功能，是限制攻击面。

第三关：站点不一定给

规则写对了，站点也不一定给你数据。

现在很多资源站前面挂了一层挑战页：先证明你是浏览器，才给你真页面。这类拦截对 XPath 是致命的——你请求拿到的是挑战页，解析出来零条，看起来像规则写错了。

Kazumi 的处理是把这件事显式建模成一类错误：CaptchaRequiredException。

检测有三条路，规则里选一条：

• XPath：页面上存在某个元素就算挑战（比如某个特定的 div#challenge）
• 文本：响应原文里包含某段字符串
• 正则：响应原文匹配某个模式

除了这层页面级检测，代码里还有一道更硬的判据：看响应头里有没有 cf-mitigated: challenge。这个头是 Cloudflare 托管挑战自己标的，碰上响应体为空、被压缩坏、或者 Dio 在某些平台上拿不到 body 的情况，它是唯一还活着的线索。

final cfMitigated = response?.headers.value('cf-mitigated');
if (cfMitigated?.toLowerCase() == 'challenge') return true;

判定为挑战之后，流程切到 WebView：把搜索页真的加载出来，让人看见挑战长什么样，再按规则指定的方式过掉它。过法有三种——图片验证码（抓像素给用户看，用户输入，程序去填输入框、点提交）、自动点击「我不是机器人」这类按钮、以及规则里直接给一段自定义 JavaScript。

过了之后，cookie 存下来，回头重试那次 XPath 搜索。这时请求带着凭证，拿到的就是真页面。

这里有一段是整篇里最像「踩过坑的人写的」。

Cloudflare 发的清除 cookie，是绑定 User-Agent 的。它记住的是「这个 UA 刚才过了验证」，换一个 UA 来，等于没验证过。

而 Kazumi 的规则里允许写自己的 userAgent，代码里还会在没有规则 UA 时随机挑一个。于是出现必然的矛盾：验证时用的是 A 浏览器、UA 是 A；验证完发 XPath 请求，规则说 UA 用 B。站点一看凭证和 UA 对不上，又给你一张挑战页。

解法直白得有点狠：

// Clearance cookies are bound to the User-Agent they were issued to,
// so the verified UA overrides the rule's own; sending a different one
// would make the site serve the challenge page again.
if (verifiedUserAgent != null) 'user-agent': verifiedUserAgent;

验过证的 UA，优先级高于规则里写的 UA。 规则作者想指定 UA 的自由，在通过验证之后被剥夺了——因为不剥夺就必然复发挑战页。同一个函数里还有个细节：请求头全部转成小写键，这样规则里写 User-Agent 和我们写 user-agent 会撞在一起被后者覆盖，而不是发出两个互相打架的头。

还有一处更像历史遗留：XPath 的搜索请求带 cookie，章节请求不带。代码注释写得很坦白——「历史上章节请求就是不带 cookie 的，只有搜索带」。这种句子一看就是被现有行为逼出来的，不是设计出来的。

第四关：剧集页里没有视频地址

到这里，最容易被误解的一步来了。

很多人以为抓完剧集链接，下一步就是从那个链接里取出 mp4 地址。不是。

剧集页面里通常没有视频地址。它是一个播放页：页面加载后跑一段 JS，拉播放器脚本，播放器再去请求播放列表，最后才把流地址塞进 <video> 或者喂给 MediaSource。

你能抓到的，是一个会自己长出视频地址的网页，而不是一个视频地址。

所以 Kazumi 的做法是：开一个不显示的 WebView，把剧集页真的加载出来，让页面自己跑，然后在它跑的过程中把地址截下来。

自己用 HTTP 客户端请求那个页面，拿到的只是一堆带 onclick 的 HTML，JS 不会执行，播放器不会初始化，流地址永远不会出现。就算能执行，很多站还会校验 referer、校验 cookie、校验某个只在浏览器里才有的对象。你得有一个真的浏览器环境，才有资格看见那条流。

WebView 的配置也能看出目的：随机 UA、禁图片（blockNetworkImage 和 loadsImagesAutomatically 都关掉）、关缓存。禁图这一条尤其说明问题——它根本不需要给你看，只需要页面把 JS 跑完。

截流的具体手法，是注入了两段脚本，都在文档开始时注入（AT_DOCUMENT_START），赶在页面自己的脚本之前把自己挂上去。

第一条：劫持响应读取。

const _r_text = window.Response.prototype.text;
window.Response.prototype.text = function () {
  return new Promise((resolve, reject) => {
    _r_text.call(this).then((text) => {
      resolve(text);
      if (text.trim().startsWith("#EXTM3U")) {
        window.flutter_inappwebview.callHandler('VideoBridgeDebug', this.url);
      }
    }).catch(reject);
  });
};

同一段里还把 XMLHttpRequest.prototype.open 包了一层，监听 load 事件读 responseText，同样的判据。

判据是 #EXTM3U——m3u8 播放列表的第一行。不看 URL 后缀，原因很简单：大量源的地址长得像 https://x.com/hls/abc123?sign=...，一个 .m3u8 都没有。看内容开头比看地址可靠得多。

第二条：盯 video 标签。

用 MutationObserver 监听整个文档树的属性变化和新增节点，盯着 <video src> 和 <source src>。拿到非空、不是 blob:、不含 googleads 的地址就收工，顺手把 observer 断开。

跳过 blob: 是必须的——用 MediaSource 播放的页面，video.src 永远是 blob:https://... 这种本地伪地址，真正的流在别处。所以对这类页面，第一条劫持才是唯一出路。

第三条：老路子，扫 iframe。

规则里的 useLegacyParser 打开时，注入的是另一段脚本：盯所有 <iframe> 的 src，拿到就回抛。Dart 侧再用正则从 iframe 地址的查询参数里抠出真正的地址：

final regExp = RegExp(r'(http[s]?://.*?\.m3u8)|(http[s]?://.*?\.mp4)',
    caseSensitive: false);
params.forEach((key, value) {
  if (regExp.hasMatch(value)) matchedUrl = value;
});

逻辑很朴素：有些站把播放页整个套在 iframe 里，iframe 地址带着一堆参数，其中一个参数的值就是 .m3u8。挨个参数试一遍，谁匹配取谁。它显然是给「地址带后缀」的老站点准备的，所以被标成了 legacy。

拿到 .m3u8 也不等于拿到干净内容。HLS 的播放列表是一份纯文本清单，按时间顺序列着一堆分片，有些站会把广告剪成几个分片直接插进去——它和正片在同一条流里，跳过键没用，画面识别也无从下手。

Kazumi 的处理在清单层，靠 EXT-X-DISCONTINUITY。这个标签本来是给「分段之间编码参数变了」准备的：正片切广告再切回正片，前后时间戳不连续，就得标一个。但正因为广告插播一定造成不连续，它顺手成了广告的指纹。

判据很朴素：按 discontinuity 分组把清单切成若干段，算出每段总时长，最长的那段当正片，其余段里明显偏短的判为广告，剔掉。注释写着这是「模仿 FFmpeg 的 hls_ad_filter」——思路确实不是它发明的，转码工具里早有同名滤镜干同样的事，区别只是 FFmpeg 跑在服务端，它跑在客户端。

一个 WebView 只能干一件事

截流这套办法有个硬约束：一个 WebView 同一时刻只能加载一个页面。

而用户可能同时在切集、在下载、在预载下一集。全挤在一个 WebView 里，会互相踩。

代码里的处理是两层：单实例内串行，实例之间并行。

单实例内，用一个 Future 链把请求排成队：

final resolveFuture = resolveTail.then((_) => _runResolve(...));
_resolveTail = resolveFuture.then<void>((_) {}, onError: (_) {});

后一个请求挂在前一个的尾巴上，前一个失败也不影响后一个排队。同时，新请求进来会先把上一个标记取消——不是等它跑完，是让它在下一次检查点时自己抛出去。

实例之间是一个池子：VideoSourceResolverPool，上限五个 worker，用租约（lease）管。同一个 key（同一集）已经有租约在手，第二次请求直接拿不到，避免重复解析。租约释放时，如果这个 worker 该退休了，就顺手销毁，不留着占内存。

每个解析还带着超时，默认 15 秒。实现方式是把「解析完成」和「取消信号」两个 Future 扔进 Future.any 竞速，谁先到算谁。页面加载完立刻 unloadPage() 跳去 about:blank 把资源放掉——WebView 实例留着复用，页面不留在内存里。

第五关：播放器是 libmpv

拿到流地址之后，事情才交回播放器。

播放这块的底层是 mpv，通过 media_kit 这层 Dart 绑定接进 Flutter。这里要说清一件事：mpv 不是一个「播放控件」，它是一个完整的播放内核——解封装、解码、渲染全在自己身上，自带的 ffmpeg 负责读 m3u8 和 mp4，不借系统解码器。

这解释了它为什么敢接一堆来源杂乱的流：系统的 ExoPlayer、AVPlayer 对畸形清单和异常时间戳的容忍度，跟 ffmpeg 那套不是一回事。也解释了它为什么非得自己塞一个播放器进来——用系统播放器，等于放弃一半的源。

代码里的初始化只有一行 MediaKit.ensureInitialized()，之后所有行为都是运行时改属性。招数不多，但都很实在：

选渲染器。 Android 上分三档：gpu（OpenGL）、gpu-next（Vulkan）、mediacodec_embed（硬件解码直出）。默认 auto，判断条件是系统版本——Android 14 及以上走 gpu-next，以下走 gpu。注释把理由写明白了：Vulkan 1.2 在着色器上表现更好，但 Android 13 及以下有些机型支持不佳，会直接黑屏。这不是「新系统就上新技术」的偏好，是被黑屏教育出来的分界线。

降功耗。 选了 mediacodec_embed 就同时把 hwdec 设成 mediacodec，并且强制把超分关掉——不是提示一句「可能不支持」，是直接把档位拧到 off。因为硬件解码直出把画面直接交给显示层，中间没有可以插 shader 的位置，这个组合在结构上就不成立。

保音调。 倍速用 scaletempo2=max-speed=8，变速不变调，上限八倍。Android 上音频输出还要显式指定 ao（audiotrack 或 opensles），否则某些机型会掉到静音。

控缓存。 demuxer-max-bytes 与 demuxer-max-back-bytes 默认放到 1.5 GB，这就是 README 里「播放时内存占用较高」的来源——它在拿内存换拖进度条时的顺滑。开了低内存模式、或者检测到走的是计量网络（手机热点），这两个值会掉到 2 MB。

四件事没有一件是「换个 Widget 就能做到」的。它们全是 mpv 的属性，说明这个播放器在这里被当成一台可编程的引擎在用。

超分的实现同样「mpv」：把 Anime4K 的 GLSL 文件拷到一个可读目录，运行时发命令：

await pp.command(['change-list', 'glsl-shaders', 'set', shaderPathList]);
// 关闭时
await pp.command(['change-list', 'glsl-shaders', 'clr', '']);

shaderPathList 是把若干个 .glsl 的绝对路径拼成一个字符串，Windows 用 ; 分隔，其他平台用 :。这就是 mpv 的原生约定，Kazumi 只是照着拼。

两档滤镜，串法不一样：

质量档：先压高光，再上 VL 档的 CNN 复原，再 VL 档的 2 倍上采样，然后根据目标分辨率自动降采样，最后补一道 M 档上采样。

效率档：压高光，M 档和 S 档各复原一次，M 档上采样，自动降采样，再补一道 S 档上采样。

VL / M / S 是 Anime4K 的三档网络体量，越大的恢复细节越多、算得越慢。质量档用 VL 打头阵，效率档用 M+S 堆叠——用两道小网络换一道大网络的活，这是移动端常见的省算法。那些 GLSL 是真长，VL 那档的复原着色器里塞的是训练出来的卷积权重，不是手写的数学公式。

超分不是免费的。

播放器设置里有四种渲染器，选项说明里只有 mediacodec_embed 那一条后面明写着：功耗最低，不支持超分辨率。

不是「可能不支持」，是结构上不可能。超分是在解码后的画面上插一道全屏卷积，画面得先进 GPU 的渲染管线；硬件解码直出是把结果直接交给显示层，中间没有那个可以插 shader 的地方。

所以想开超分，就必须放弃最低功耗那条路。想在低端机上省电，就得关掉超分。这两件事只能选一个。这笔账在移动端特别贵——VL 档的卷积不是一次，是每一帧都跑一遍；4K 输出意味着每个像素都在算。结果是发热、掉帧、耗电三件事一起上来。效率档存在的意义，就是给这条线留个退路。

播放器这一层还接着几根管子：后台播放用一套跨平台音频服务，桌面上各自对接系统媒体控制（Linux 的 MPRIS、Windows 的媒体会话），系统面板上按暂停能真的暂停；投屏走 DLNA，把地址丢给电视；外部播放器则是把 URL 和 referer 一起交出去。

这些能力全是「把地址交出去」的变体。所以前面那句「反盗链的源给不了外部播放器」在这里会露出来：DLNA 和外部播放器都拿不到那个已经验证过的浏览器环境，地址出门就失效。

只有内置播放器能带着整套上下文去请求。这也是这套架构的本质——它的能力来自「我模拟了一个浏览器」，而不是「我破解了地址」。 一旦离开那个环境，地址就废了。

除这五关，还有几件事

弹幕不自己攒。 走弹弹 play 的开放接口：按番剧名和集数去匹配，匹配上了把列表拉回来。格式是 m 加 p 两段，m 是内容，p 是逗号分隔的四段——时间、类型、颜色、来源，一条长这样：{"m": "来了来了", "p": "12.345,1,16777215,BiliBili"}。类型里 1 是滚动、4 是底部、5 是顶部；颜色是 RGB 整数。这个格式几乎是照着 B 站早期 XML 弹幕抄的，好处是现成的弹幕库都能直接吃。

匹配这一步是整条链路里最容易无声失败的地方。番剧名差一个字、季数标错、集数编号从 0 还是从 1 开始，都可能匹配到别的番，或者干脆匹配不到。匹配不到时界面不报错，就是一条弹幕都没有——你得自己判断是「这集确实没人发」还是「认错番了」。

一起看靠一个老协议。 走的是 SyncPlay，一个专门为「多人同步播放本地文件」设计的开源协议。握手是 Hello：报房间名、用户名、自己支持哪些特性。之后不断交换 State：播到第几秒、是不是暂停、这次改动是谁发起的。再加 Ping 往返测延迟。

代码里有个细节值得单独说：RTT 用滑动平均算，新样本权重 0.85。意思是「以历史为主，新值只修一点点」。这样网络抖一下，同步不会跟着跳一下；代价是真变慢时，要过好几拍才追上来。一秒钟的漂移没人注意，一秒钟的抖动所有人都能感觉到——所以他们选了怕抖动。

追番记录不存状态，存事件。 同一个功能，两台设备各看了一半，怎么合并？

最直觉的做法是「后写的覆盖先写的」。一旦涉及进度，这条规则马上就错——你在手机看到第 8 分钟，电脑看到第 12 分钟，按时间戳取大的，看上去对。但如果你在手机上往后拖了一下又退回去，这个动作也会刷新时间戳，结果电脑上那段真看的进度被一条假进度覆盖了。

Kazumi 的做法是每次进度变化往一个 .jsonl 文件里追加一行事件：哪个设备（deviceId）、第几个序号（seq）、哪一集、哪条线路、进度到哪、什么时候改的。

{"device":"a1b2c3","seq":418,"ep":7,"road":1,"progressMs":735000,"time":1762000000}

用事件而不是状态，合并就变成一次重放：把两台设备的日志按设备分组、按 seq 排序，逐条应用，最后得到的状态是确定的。没有「谁覆盖谁」的歧义，因为从来没有覆盖，只有追加。

代价是文件会一直长。所以有个阈值：日志超过 1 MB 就做一次压实——把所有事件重放成一份快照，日志清空，从零开始记。压实不能占 UI 线程，得扔进 isolate。同步本身走 WebDAV，服务端就是一个网盘，什么逻辑都没有，所有合并在客户端完成。这也解释了为什么合并逻辑必须写得足够确定：它没有第二道保险。

它能干什么，不能干什么

把功能摊开，它其实是个相当完整的播放器：多源切换、选集、倍速、字幕、弹幕、投屏、外部播放器、下载、追番列表、跨设备同步、超分、一起看。

但边界同样清楚，而且每一条都能从代码里找到依据。

它不生产内容，也不托管内容。 规则指向哪个站，它就去哪个站取。站点有没有授权、片源合不合法，都不在它手里。

它不保证源可用。 规则是社区维护的，站点改版就失效。App 能做的只是标个「搜索有效」——那条标签背后是一次真请求、真解析，它没法知道你没在骗它。

它管不了广告。 README 里写得直白：项目本身没插广告，看到广告是视频源塞的。有些规则会开 adBlocker，但那是逐站适配，不是通用能力。

不是所有源都能给外部播放器。 一部分源用了反盗链，Kazumi 能过（因为它有一个真浏览器环境），把地址交给外部播放器就过不了。

三本账

时间账。 写一条规则，快则十分钟，慢则一小时。要打开站点、翻开发者工具、把结构看懂、写出五行、试错几次。规则仓库里有现成的可以抄，但抄来的东西别人能维护，你不一定能。

维护账。 站点改版是常态，不是意外。一条规则活了半年算长寿。这意味着「配好就不用管」是幻觉，实际是「隔一段时间就得回去看一眼」。这也是为什么规则要带版本号、要能一键更新，为什么规则里还要声明一个 api 版本——新规则被老客户端拿到时会响亮地拒绝，而不是解析出一半、在播放时才莫名其妙地失败。

合规账。 这一本最重，也最容易被跳过。它是一个「采集 + 播放」的框架，采集对象是别人网站上的内容。技术中立不等于使用中立，怎么用它，责任在使用的人。写这篇是拆技术，不是推荐用法。

三本账加起来，能得出一个不算好听的结论：这类工具的价值不在「省了会员费」，在「你能不能接受长期维护一份自己写的抓取配置」。

如果我来改，会先动这三处

读代码时记了几笔，不属于「bug」，属于「当初这么写有道理，现在该还了」。

第一处：把章节请求的 cookie 补上。 现在是搜索带 cookie、章节不带，注释写着这是历史行为。结果是一种很难查的状态——搜索通了，点进去章节列表空白，用户会以为规则写错了。这条债拖得越久，改的时候越怕影响别的站点。

第二处：把 UA 接管做成显式的。 通过验证之后，规则里写的 UA 被静默覆盖，规则作者完全不知道。至少应该在界面上标一下「本站已接管 UA」，别让人对着自己写的字段怀疑人生。

第三处：把嗅探脚本从四份实现里抽出来。 同一段 JS 在四个平台各有一份，改一处要改四处，还得保证行为一致。这类重复不会马上出事，但会慢慢长成「改了三处忘了第四处」的经典现场。

这三条有个共同点：都不是能力问题，是可维护性问题。一个项目能跑起来靠的是能力，能活五年靠的是这个。

结语

回到开头那个空界面。

装上之后什么都没有，这是它最不讨喜的地方，也是它唯一诚实的地方。

它没有假装自己知道片源在哪。它把这件事交出来：站点长什么样，你告诉我；怎么从里面取，我照做。

这套设计的每一处都在为「别人会变」做准备——规则带版本、引擎分三段、策略可切换、反爬做成配置、嗅探留三条路、解析器留一个 legacy。这些都不是优雅的设计，是应对变化的补丁。补丁摞补丁，就成了一个能用的东西。

而它真正做的事，其实只有一句话：把「网页里能看见的东西」翻译成「播放器能用的东西」。

翻译这件事，从来没有一劳永逸的版本。所有靠规则活着的工具，最后维护的都不是代码，是别人网站的耐心。这也是在 云栈社区 里不少做工具开发的人常聊到的一点——规则会过时，架构得能扛。

参考

1. Kazumi 仓库：https://github.com/Predidit/Kazumi — 规则模型、解析策略、WebView 嗅探与超分的一手材料
2. 规则仓库：https://github.com/Predidit/KazumiRules — 各站点的真实规则，可以对照着看五行怎么写
3. 规则开发文档：https://kazumi.app/docs/rules/develop-rules — 字段含义与编写流程的官方说明
4. Anime4K：https://github.com/bloc97/Anime4K — 实时超分着色器的原始项目与档位说明