企业官网建设流程全解析

Capptivo 是一款免费开源的跨平台（Mac/Windows/Linux）屏幕录制与演示视频编辑工具，被很多人视为 Screen Studio 的平替。它的视频导出模块藏着不少工程巧思：三级编码路线降级、停滞看门狗（Stall Watchdog）、真实帧探针，共同保证进度条永远不会卡死在某个百分比上。这篇文章带你完整看懂这套容错设计是怎么做到的。

为什么视频导出容易"卡死"？

做过桌面端视频导出的同学大概都见过这种场景：编码器接口显示"支持"，但实际编码时永远不吐数据——不报错、不超时、不回调，只是沉默。Capptivo 的源码注释里就记录了这样一个真实故障：WebView2 的 WebCodecs H.264 编码器configure()之后可以无限期地"接收帧"却从不输出一个字节，导致 1080p30 的导出卡死在第 23 帧左右，也就是用户反馈里最经典的"卡住在 1%"。

针对这类"沉默式失败"，Capptivo 的导出系统（位于 src/windows/editor/export/）确立了一条核心原则：

停滞不是致命错误，而是"这条路线在这台机器上死了"的信号——自动换下一条路线。

三级降级：从最快到最通用的编码路线

Capptivo 的 MP4 导出并非只有一条路，而是一个有序路线表，按优先级依次尝试，前一条失败才轮到下一条。路线规划的唯一入口在 planMp4Routes：

几个值得注意的设计细节：

• 原生引擎优先：编辑器把一份"导出快照"交给 Rust 引擎，渲染、编码、混流全在后端完成，见 exportNative.ts 的模块注释与 native_export.rs。一旦失败且不是用户取消，立即释放目标文件、回落到 WebView 路线。
• 二级路线必须先"验证"才可用：VideoEncoder.isConfigSupported()在 WebView2 上并不可信（它可能为实际会死机的配置返回supported: true）。所以 annexBProbe.ts 会真实编码 3 帧、要求真的拿到压缩字节，单个候选给 4 秒宽限期，全部候选合计 12 秒预算——超时就放弃该路线，代价只是几百毫秒，而不是整个导出。
• 路线越少越好：源码注释直白地说"少即是功能"，每条多余的路线都是"在 A 机器上能用、B 机器上不能用"的新组合。
• 取消与 GPU 上下文丢失是终止态：用户点了取消就不再重试；GPU 已死就换路线只会更慢地再失败一次（见 exportVideo.ts 中exportMp4的注释）。

停滞看门狗：给"每一次等待"都设上闹钟

如果说路线降级是"换路走"，看门狗就是"判断什么时候必须换路"。核心实现只有 100 行出头：exportStall.ts。

三档时间阈值一目了然：

看门狗的工作方式非常克制：StallWatchdog 只盯一个单调递增的进度令牌（例如"已产出块数 + 已完成写入数"）。数字上涨说明有进展，重置计时；数字不动超过阈值，抛出ExportStallError——注意它不是致命错误，上层捕获后推进到下一条路线。

配套的 withDeadline 则负责给那些"承诺永不超时"的 API 套上闹钟：WebCodecs 的flush()卡死时它根本不会 resolve，于是withDeadline(encoder.flush(), 30_000, ...)在 exportH264Ffmpeg.ts 里强制把它变成失败。源码注释称之为"导出能挂在 99% 的第二个位置"。

这套机制覆盖了导出中的每一类等待：

• 编码背压等待：编码队列排满时循环会自旋，每转一圈都调watchdog.check(token)，见 exportH264Ffmpeg.ts——正是"以前会无限自旋"的那个循环。
• GPU 像素读回等待：RGBA 路线用异步 PBO 读回让第 N 帧的传输与第 N+1 帧的合成重叠（asyncReadbackRing.ts 的 3 槽 FIFO 环）；围栏 2 秒不亮就强制落定、整体切换同步读回——降级而不中断，因为那是 Windows 上唯一的 MP4 路线。
• 解码层也有降级：首选"顺序解码"（文件走一遍，每帧一次解码）；若 WebCodecs 解不了这台机器的编码，退化为"逐帧 seek"，会从上一个关键帧重解最多约 250 帧、慢约 60 倍。decodeFallback.ts 专门把这类退化的原因写进日志，回答用户"为什么导出这么慢"。

用户视角：这一切意味着什么？

对普通用户来说，这套设计带来三个直接体感：

1. 进度条永远要么在走、要么给出结果：8 秒无进展自动换路线，用户最多感知到一次短暂的进度归零，而不是一晚上的等待。
2. 任何机器都有兜底：rgba-ffmpeg不依赖 WebCodecs，硬件编码器由 Rust 侧原生探测，最坏情况也能出片。
3. 失败有迹可循：每次路线切换、每次停滞都会写进导出日志（[export] path=...、MP4 export failed — routeA: ...; routeB: ...），配合应用数据目录下保留最近 200 条的诊断码，反馈问题时可以快速定位。

想动手研究这套容错实现，可以直接从以下入口读起：

• 路线总调度：exportVideo.ts
• 路线规划：exportRouting.ts
• 看门狗与超时：exportStall.ts
• 真实帧探针：annexBProbe.ts
• 原生引擎桥接：native_export.rs
• 解码退化说明：decodeFallback.ts

写在最后

"永不卡死"靠的不是祈祷，而是三个朴素原则：给每次等待设定时限（看门狗）、声明的支持不算数，实测才算（探针）、永远留一条不依赖 fancy 特性的底路（RGBA 兜底）。这三个原则不只适用于视频导出，任何要跑在千台不同机器上的长时任务都值得借鉴。如果你也在用 Capptivo 做产品演示录制，遇到导出异常时不妨看看应用日志里的路线切换记录——它往往比错误弹窗更能说明问题出在哪一级。