PureLive 上游 Issue 审计实录:v2.6.0 维护分支对 Windows 小窗、关注刷新与播放器链路的系统性修复
PureLive 上游 Issue 审计实录:v2.6.0 维护分支对 Windows 小窗、关注刷新与播放器链路的系统性修复
本文基于 pure_live 维护仓库的 ISSUE_AUDIT_2026_08_23.md 展开。该文档记录了维护分支对上游
liuchuancong/pure_live最近两日公开问题(#765、#767、#769、#770、#771、#773、#774)的根因复核与修复落点。文中将逐一拆解每个 Issue 的复现链路、根因定位、维护分支的处理策略,并给出对应的源码实现路径与测试佐证,帮助读者理解一个多平台直播客户端的稳定性维护是如何在"只更新维护仓库、不向上游提交 PR"的约束下完成的。
审计背景与基线
本次审计发生于 2026-08-23,针对的是上游 liuchuancong/pure_live 最近两日新增问题,以及仍与当前维护分支稳定性相关的公开问题。审计的关键约束如下:
- 代码基线:真实合并至上游提交
c3ae29bb,维护分支在冲突语义上按稳定性实现整合; - 操作边界:本轮只更新维护仓库,不向上游创建 Pull Request——即所有修复以维护分支自洽为目标,不做上游反向合并的承诺;
- 版本目标:修复随 v2.6.0 阶段稳定版(版本号
2.6.0+4076)发布,并完成 Android、Windows、Linux、macOS、iOS 五个平台的串行构建与质量门禁。
这种"只进维护分支"的审计模式意味着:每个修复不仅要解决平台侧的 bug,还要保证不与上游后续合并冲突、不破坏已有用户配置。文末会看到,这一点直接影响了 #770 的"默认策略只作用于新配置"和 #765 的"星标置顶保留为产品需求"等决策。
结论总览
原文档以一张结论表概括了全部 6 个 Issue 的复现链路与维护分支处理,这里完整保留并逐项展开:
| Issue | 复现链路与根因 | 维护分支处理 |
|---|---|---|
| #765 Windows 小窗不记忆位置/大小、希望星标置顶 | 每次进入都重新计算主屏右下角固定矩形;窗口监听还会把小窗尺寸短暂写入主窗口尺寸设置。上游后续实现只按显示器保存坐标、未保存用户调整后的尺寸,并与现有全局窗口监听重复。星标属于新增排序能力,并非现有状态损坏 | 合并为单一路径:独立持久化小窗宽高与坐标,移动/缩放后去抖保存,增加记忆开关与重置入口;恢复时按原显示器工作区校正,显示器移除后回到应用所在屏;小窗与主窗口尺寸分开更新。特别关注继续使用现有长按标签分组,本稳定版不擅自改变"全部"页的热度/在线人数排序 |
| #769 切换直播间列表越界空白 | 弹窗内 ListView 继承外层 PrimaryScrollController,并使用允许视觉越界的默认滚动物理效果 |
列表使用独立控制器语义、ClampingScrollPhysics 与硬裁剪,首尾边界保持在内容区 |
| #770 iOS 自编译仅 IJK 有画面且低帧 | iOS 新安装仍沿用 MPV 默认值;原生层未向统一刷新率服务回报 ProMotion 上限 | iOS 新配置默认 IJK,已有显式选择不迁移;补齐显示模式通道并保留 CADisableMinimumFrameDurationOnPhone |
| #771 多文件字体、弹幕字体、SC 与强制销毁黑屏 | 下载器写入 fonts/,管理页曾读取 fontsDir/;选择文件未持久化/冷启动注册;SC 页未直接观察 RxList;非 Exo 纹理等待自身尺寸才挂载,形成初始化环 |
统一字体目录和所选文件持久化,主字体/弹幕字体冷启动注册;SC 实时快照与房间代次;原生纹理先挂载、再用真实尺寸更新布局 |
| #773 链接跳转及普通入口无法关注 | 按钮缓存局部布尔值并依赖 EventBus 刷新;链接占位房间详情补全后身份变化,旧局部状态与持久列表脱节 | 按钮直接观察收藏列表并用平台+房间号复合身份;详情未完成时显示加载态;跳转等待导航完成 |
| #774 v2.6.0 关注页手动刷新失效、未开播仍显示 | 每个平台页虽然重新包了 EasyRefresh,但子列表又显式安装 Android ClampingScrollPhysics,边界位移先被外层物理模型消耗,刷新头只有回调配置而没有可触发的拖动链路。与此同时,冷启动核验与 450 ms 后的 resumed 刷新通过 _refreshEpoch 互相取消,失败房间继续沿用上次进程的开播位;部分平台还把网络异常伪装成"已下播"成功结果 |
改用 EasyRefresh.builder 并把其物理模型直接交给当前平台的唯一纵向列表,加入可见 Material 动画和真实拖动 Widget 回归;启动期间发布"状态未知但位置稳定"的非持久预览,所有刷新经单事务锁串行,启动/恢复/手动触发绕过失败冷却;CC、Twitch、SOOP 使用严格元数据刷新路径,虎牙 REPLAY 进入录播分组 |
| #767 Windows 4K/高 DPI GPU 偏高 | 视频原生视图曾按源尺寸经 FittedBox 放大/裁切,窗口变化与呈现更新可能重开数据源 |
非 Exo 输出按可见视口和 applyBoxFit 约束;画面比例切换仅改呈现 revision,不重试数据源 |
#765:Windows 小窗几何——从"主屏固定矩形"到"按横竖屏独立记忆"
根因:几何状态的三重错位
Windows 小窗(画中画/浮窗播放)问题的复现链路可以拆成三层:
- 位置不记忆:每次进入都重新计算主屏右下角固定矩形,用户上一次摆放的位置被直接丢弃;
- 尺寸污染:窗口监听会把小窗尺寸短暂写入主窗口尺寸设置,导致小窗和主窗口的几何状态互相干扰;
- 上游实现不完整:上游后续实现只按显示器保存坐标,没有保存用户调整后的尺寸,并且与维护分支现有的全局窗口监听重复。
此外,"星标置顶"属于新增排序能力,并不属于现有状态损坏——这决定了它在本次修复中只被记录,不被强行实现。
修复:单一几何持久化路径
维护分支的处理方式是合并为单一路径,核心思路可以概括为"小窗几何独立于主窗口、按画面方向分别记忆、损坏数据安全回退"。
在源码中,这一设计由 FloatWindowGeometry 承载:
@immutable
class FloatWindowGeometry {
const FloatWindowGeometry({this.landscape, this.portrait});
final Rect? landscape;
final Rect? portrait;
Rect? forPortrait(bool isPortrait) => isPortrait ? portrait : landscape;
FloatWindowGeometry withRect({required bool isPortrait, required Rect rect}) {
return isPortrait
? FloatWindowGeometry(landscape: landscape, portrait: rect)
: FloatWindowGeometry(landscape: rect, portrait: portrait);
}
// encode() / decode() 使用 JSON 序列化,
// 解析失败或矩形非有限/为空时一律回退为空记忆,绝不抛错。
}
关键设计点:
- 按横屏/竖屏分别保存:同一个手机竖持与横持时屏幕可用空间不同,横屏流与竖屏流也需要不同的窗口形状,因此
FloatWindowGeometry用landscape与portrait两个Rect分别记忆; - 损坏数据安全回退:
decode()对空串、非法 JSON、非 4 元素数组、非有限数值、空矩形全部返回"无记忆",因为该值会随备份/设置文件持久化,损坏时应该表现为"窗口按默认位置打开",而不是"窗口无法打开"; - 持久化字段:最终编码为字符串写入设置项
floatWindowGeometry(见 floating_playback.dart 中SettingsService.to.player.floatWindowGeometry.value)。
窗口行为与记忆回写
floating_playback.dart 中,小窗的默认放置参数与记忆回写逻辑互相配合:
placement: const FloatingWindowPlacement(
config: FloatingPlacementConfig(
width: 380,
height: 214, // 16:9 流的可观窗口(库默认 160×90 只是缩略图)
minWidth: 200,
minHeight: 112,
maxWidthFraction: 1.0, // 允许占满屏幕,仍被钳制在屏幕内
resizableByDrag: true,
resizeHandles: FloatingResizeHandle.all,
resizeKeepsAspectRatio: false, // 宽高自由,用户改了什么就记什么
),
),
initialRect: _rememberedFloatRect(isPortraitSurface),
onRectChanged: (rect) => _rememberFloatRect(isPortraitSurface, rect),
对应文档中"移动/缩放后去抖保存"的要求,回写逻辑同时校验 rect.isFinite 与 rect.isEmpty,非法矩形不会被写入设置。该几何实现由 float_window_geometry_test.dart 覆盖,测试项包括:
- 横屏与竖屏保存独立的窗口矩形;
- 只覆盖自身方向的旧矩形,另一个方向不受影响;
- 空记忆方向回退到默认锚点;
- 编码/解码 JSON 往返一致;
- 空串、
null、[1,2,3]、{"landscape":"x"}等损坏负载全部解码为无记忆; - 空高度矩形与非数值矩形不被记忆。
决策边界:星标置顶为什么没做
Issue #765 中的"星标置顶"诉求被明确保留为产品排序需求:它属于新增排序能力,会改变"全部"页当前的热度/在线人数排序规则。文档强调"本稳定版不擅自改变排序",避免绕过用户现有的长按标签分组规则。这个边界值得所有维护者借鉴:修复不越过产品语义,只解决状态损坏。
#769:直播间切换弹窗的列表越界空白
根因:继承外层的 PrimaryScrollController + 默认物理效果
问题表现为切换直播间列表时出现越界空白。根因有二:
- 弹窗内
ListView没有声明primary: false,继承了外层的PrimaryScrollController,两个滚动视图共用同一控制器语义; - 使用了允许视觉越界的默认滚动物理效果(Android 上的
ClampingScrollPhysics允许一定的越界位移,iOS 上则默认回弹),在弹窗边界处把内容拖出了可视区,产生空白。
修复:独立控制器 + 硬边界物理模型
维护分支的做法是:列表使用独立控制器语义(primary: false),配合 ClampingScrollPhysics 与硬裁剪,让首尾边界始终保持在内容区。
这一策略在 super_chat_page.dart 中有直接体现:
return ListView.builder(
primary: false, // 不继承外层 PrimaryScrollController
physics: const ClampingScrollPhysics(), // 硬边界,不允许越界回弹
...
);
更进一步,项目在 pure_live_scroll_physics.dart 中封装了两套物理模型,把"内容列表"和"有限选择器"严格区分:
PureLiveScrollPhysics:按平台自适应——iOS/macOS 使用BouncingScrollPhysics保留原生回弹,其余平台使用ClampingScrollPhysics;PureLiveBoundedScrollPhysics:继承ClampingScrollPhysics,并在adjustPositionForNewDimensions中把偏移强制clamp到minScrollExtent..maxScrollExtent,即使内容收缩、路由仍挂载,也绝不越过首尾边界。
后者正是文档所说"硬裁剪"的源码级实现,适用于导航条、分页视图等有限选择器场景,与弹窗列表的修复思路完全一致。
#770:iOS 自编译播放器默认策略与 ProMotion 刷新率
根因:新安装沿用 MPV 默认值 + 刷新率服务缺位
iOS 自编译场景下,新安装用户沿用 MPV 播放器默认值,导致只有 IJK 有画面且帧率偏低;同时原生层没有向应用的统一刷新率服务回报 ProMotion 屏幕的上限,弹幕/画面无法跑到 120 Hz 档位。
修复:默认策略 + 显示模式通道
- 新配置默认 IJK:iOS 新安装默认使用 IJK 播放器;已有显式选择的用户不迁移——这再次体现了"新策略只作用于新配置"的兼容性原则,避免强制改变老用户的播放体验;
- 补齐显示模式通道:统一刷新率服务通过
MethodChannel('pure_live/display_mode')与原生通信。以 display_mode_service.dart 为证,DisplayModeService提供:
static Future<DisplayModeInfo?> setHighRefreshRate(bool enabled) async { ... }
static Future<DisplayModeInfo?> refreshInfo() async { ... }
返回的 DisplayModeInfo 携带 currentRefreshRate、maxRefreshRate、preferredRefreshRate、supportedRefreshRates、displayId、宽高等字段,原生层还通过 displayModeChanged 回调主动推送变化。
- 保留
CADisableMinimumFrameDurationOnPhone:该键确实存在于 ios/Runner/Info.plist 中,用于允许 iPhone 在 ProMotion 屏上突破系统默认的最小帧间隔限制,从而把弹幕渲染驱动到屏幕刷新率上限。
#771:字体目录漂移、SC 实时性与强制销毁黑屏
这一个 Issue 实际捆绑了四条独立的缺陷链,维护分支按"数据一致 → 状态实时 → 纹理生命周期"三个层面分别修复:
| 子问题 | 根因 | 修复 |
|---|---|---|
| 多文件字体失效 | 下载器写入 fonts/,管理页曾读取 fontsDir/,路径约定漂移 |
统一字体目录和所选文件持久化,主字体/弹幕字体冷启动注册 |
| SC(醒目留言)不刷新 | SC 页未直接观察 RxList,消息变化不驱动 UI 重建 |
SC 实时快照 + 房间代次隔离 |
| 强制销毁黑屏 | 非 Exo 纹理等待自身尺寸才挂载,与布局形成初始化环 | 原生纹理先挂载,再用真实尺寸更新布局 |
字体目录统一
源码层面,app_path_manager.dart 把规范目录收敛为一个常量,并保留了兼容别名:
/// Canonical directory used by [FontDownloadManager] for downloaded fonts.
/// Keep this in one place so the manager page and downloader never drift to
/// different folders (the old `fontsDir` value broke multi-file font packs).
static const String fontDirectoryName = 'fonts';
// Compatibility alias retained for upstream call sites introduced in 5aa1a40a.
static const String fontCacheDir = fontDirectoryName;
注释直接点名了"旧的 fontsDir 值破坏多文件字体包"这一历史根因,并且用别名 fontCacheDir 兼容上游旧调用点,保证两处都解析到同一个规范目录 fonts/。同时,所选字体文件被持久化,主字体与弹幕字体在冷启动时完成注册——这是文档"冷启动持久字段"的落地。
SC 实时快照与房间代次
SC 页的修复方向是"实时快照 + 房间代次":SC 页直接观察 RxList 数据源,同时以"当前房间号 + 平台 + 加载代次"作为提交条件,迟到响应只结束自身任务、不覆盖新房间。这一"房间代次"隔离机制与 v2.6.0 稳定性设计中"房间详情、醒目留言、播放地址和弹幕连接均以当前房间身份为提交条件"的原则一脉相承。
#773:链接跳转与普通入口无法关注
根因:局部布尔缓存 + 身份漂移
关注按钮的问题来自两处状态管理缺陷:
- 按钮缓存局部布尔值,依赖 EventBus 刷新来同步收藏状态,EventBus 事件未发出或顺序错乱时按钮状态就与持久列表脱节;
- 通过链接打开的房间是占位房间,详情补全后身份可能变化(例如平台房间号从占位值变为真实值),旧局部状态与持久列表的键不一致,导致"已关注"状态无法匹配。
修复:直接观察收藏列表 + 复合身份
修复后,按钮直接观察收藏列表,并以"平台 + 房间号"复合身份作为匹配键。这与 live_room.dart 中定义的 identityKey 完全对应:
String get identityKey => '$normalizedPlatformId:$normalizedRoomId';
bool hasSameIdentity(LiveRoom other) => identityKey == other.identityKey;
即任何一处关注状态判断都以 platform:roomId 为稳定标识,平台房间号归一化后参与匹配。同时,房间详情未完成时按钮显示加载态,跳转动作等待导航完成——避免在详情补全前就基于占位数据做出关注判定。
#774:关注页手动刷新失效与未开播仍显示
这是本轮审计中根因链最复杂的一个 Issue,涉及滚动物理模型、刷新事务语义、失败房间状态三块。原文档给出的根因如下:
- 拖动链路断裂:每个平台页虽然重新包了
EasyRefresh,但子列表又显式安装了 AndroidClampingScrollPhysics,边界位移先被外层物理模型消耗,刷新头只有回调配置而没有可触发的拖动链路; - 刷新互相取消:冷启动核验与 450 ms 后的 resumed 刷新通过
_refreshEpoch互相取消,第二次触发的刷新会作废第一次的权威结果; - 失败状态陈旧:失败房间继续沿用上次进程的开播位(stale live bit);
- 异常伪装成功:部分平台把网络异常伪装成"已下播"成功结果。
修复一:EasyRefresh.builder 接管物理模型
维护分支改用 EasyRefresh.builder,并把其物理模型直接交给当前平台的唯一纵向列表。在 base_page_view.dart 中可以看到这个关键模式:
return EasyRefresh.builder(
header: indicators.header,
footer: indicators.footer,
controller: controller.easyRefreshController,
triggerAxis: Axis.vertical,
onRefresh: () => controller.refreshData(),
// This scrollable must use the refresh owner's physics; otherwise its
// explicit overscroll policy consumes the drag before refresh is armed.
childBuilder: (context, physics) => buildScrollable(physics),
);
源码注释直接复述了文档的根因:"滚动体必须使用刷新所有者的物理模型,否则其显式 overscroll 策略会在刷新武装之前消耗掉拖动。" 这正是"子列表显式安装 ClampingScrollPhysics 导致刷新头无法触发"的修复落点。修复同时加入了可见的 Material 动画和真实拖动 Widget 回归测试。
修复二:单事务锁串行所有刷新
favorite_controller.dart 中,旧的 _refreshEpoch 互相取消方案被替换为单事务锁:
final Lock _refreshLock = Lock(); // synchronized 包
final pending = _refreshLock.synchronized<void>(() async {
...
final updates = await _refreshRoomDetails(rooms, refreshEpoch: refreshEpoch, ...);
...
});
关键语义变化:
- 同一时刻只有一个刷新持有快照事务;
- "启动/恢复/手动触发"三类刷新绕过失败冷却(
bypassFailureCooldown: true); - 定时器、生命周期 resumed 刷新与下拉刷新都先与启动核验合并(
await startup),不再用递增 epoch 互相作废; - 每个房间引入
_refreshFailureCooldown(默认 5 分钟冷却),单房间失败只记一次摘要行,不再每个房间抛一条堆栈淹没日志。
修复三:启动期间发布"状态未知但位置稳定"的非持久预览
这一设计非常关键,由 favorite_startup_policy.dart 实现:
List<LiveRoom> markFavoriteRoomsPendingVerification(Iterable<LiveRoom> rooms) {
return rooms.map((room) => room.copyWith(status: false, liveStatus: LiveStatus.unknown)).toList(growable: false);
}
启动核验在途时,所有房间先被标记为 LiveStatus.unknown(缓存的开播位被同步作废),同时保留上一进程的三个分桶位置(在线/录播/未开播的先后顺序不变),从而做到:
- 已经下播的房间不会再被画成"直播中";
- 网格不会因为请求逐个返回而"消失又重现";
- 网络请求失败时,房间停留在"未知"而非伪造的"已下播"。
mergeAuthoritativeFavoriteRefresh 进一步规定:只有请求过的房间键才会被验证,成功响应替换服务端字段,失败响应变为 unknown,平台页之外未请求的房间保持不动——这修正了"手动刷新单平台却把无关平台标记为未知"的副作用。而 bindFavoriteRefreshResultToRequest 保证刷新结果始终绑定到请求时的收藏身份(identityKey),即使平台返回了不同的规范 id,标签和合并目标也不丢失。
修复四:严格平台刷新路径与录播分组
- CC、Twitch、SOOP 使用严格元数据刷新路径,网络异常不再被包装成"已下播"的成功结果;
- 虎牙 REPLAY 进入录播分组,回放房间不再混在直播位;
- 全部刷新经单事务锁串行,失败房间进入 5 分钟冷却,避免连续刷新对平台接口造成压力。
#767:Windows 4K/高 DPI 下 GPU 占用偏高
根因:按源尺寸放大 + 潜在重开数据源
Windows 在高 DPI/4K 屏上 GPU 负载偏高的根因是:视频原生视图曾按源尺寸经过 FittedBox 放大/裁切,窗口变化与呈现更新时可能重开数据源(重新拉流),既浪费 GPU 又引入卡顿。
修复:可见视口约束 + 呈现 revision 解耦
- 非 Exo 输出按可见视口与
applyBoxFit约束渲染,纹理尺寸不再跟随源分辨率无限放大; - 画面比例切换只改变呈现 revision(重建展示订阅),不重试数据源——拉流连接保持稳定,只有画面布局更新。
该修复属于"性能边界吸收"性质,文档中明确将其列为 v2.6.0 阶段修复的首页图片缓存驱逐、非 Exo 原生纹理初始化环、画面比例切换重开流等 CPU/GPU/内存热点之一。
醒目留言边界:实时 SC 与历史 SC 的取舍
文档在结论表之外单列了"醒目留言边界",值得单独说明:
实时 WebSocket 醒目留言已经进入统一消息列表并自动过期。斗鱼"进入直播间前已经发送且仍有效"的历史醒目留言目前适配器返回空集合;该部分取决于平台可稳定复现的历史接口。本轮重点保证进入后的实时消息、页面即时刷新、去重、过期和切房隔离。
也就是说:进入直播间之后的实时 SC 是全量保障的(进入统一消息列表、自动过期、去重、切房隔离),而进入前已发送的历史 SC 依赖斗鱼侧可稳定复现的历史接口,当前适配器返回空集合,属于明确声明的边界而非缺陷。这与 super_chat_page.dart 中 SC 以 LiveSuperChatMessage 列表为单一数据源、按消息身份去重渲染的实现一致。
验证映射:修复如何被证明
文档为每一类修复都给出了对应的验证手段,这正是"事实准确"的根基:
| 验证类别 | 覆盖内容 | 对应源码/测试路径 |
|---|---|---|
| 字体 | 目录一致性单元测试、冷启动持久字段、下载后多文件选择流程 | app_path_manager.dart |
| 关注 | 复合房间身份、外部收藏变更和链接详情补全后的响应式状态 | live_room.dart 的 identityKey |
| 关注刷新 | 真实纵向拖动触发与动画、短列表可刷新、启动未知态分桶、规范房间号回包仍合并到原收藏身份、严格平台刷新能力 | favorite_startup_policy.dart、favorite_controller.dart |
| 播放器 | 初始化先挂载、画面适配不重开数据源、切房异步代次 | floating_playback.dart |
| SC/列表 | RxList 实时快照、房间代次、首尾有界滚动 | super_chat_page.dart、pure_live_scroll_physics.dart |
| 性能 | 图片解码宽度有界、缓存不在卡片首挂载时驱逐、播放器/直播控制器显式释放 | — |
| Windows 小窗 | 同屏恢复、跨屏恢复、离屏回退与设置备份字段单元测试 | float_window_geometry_test.dart |
文档明确记录了取舍结果:"Issue #765 的小窗几何缺陷已落地修复;其'星标置顶'部分保留为产品排序需求,避免在稳定版中绕过用户现有标签和人数排序规则。"——这是本次审计最典型的一条"边界决策"。
阶段门禁与发布状态
最终门禁与产物状态见 v2.6.0 阶段稳定版。该文档记录的质量数据包括:
- Flutter Analyze 0 issue、单元与 Widget 测试 224/224 通过、公开接口探测 26/26 通过(覆盖 Bilibili、Douyu、Huya、Kuaishou、Douyin、网易 CC、Twitch 与 SOOP Live);
- 各平台按 Android → Windows → Linux → macOS → iOS 串行构建,且因涉及公共播放器代码,五个平台均从同一最终代码树重新构建;
- Android 产物经
apksigner复核 v2 签名,Windows Release 冷启动后进行了 37 个采样点的隔离实例烟雾测试,验证工作集与私有字节未随时间持续增长。
结语:一次"维护分支稳定性"的完整范本
透过 ISSUE_AUDIT_2026_08_23.md 这轮审计,可以看到 pure_live 维护分支处理上游问题的成熟方法论:
- 先复现、再定根因:每个 Issue 都追溯到具体的代码路径(滚动物理模型、EventBus 状态同步、路径常量漂移、纹理初始化环),而不是表面补丁;
- 修复优先保障稳定性:新默认策略只作用于新配置、星标置顶等产品诉求与状态损坏分离、历史 SC 边界如实声明;
- 验证映射闭环:每个修复类别都有单元测试、Widget 回归或公开接口探测兜底;
- 不向上游提交 PR 的约束:所有修复以维护分支自洽为目标,冲突语义按稳定性实现整合。
对于希望深入研究多平台直播客户端维护实践的读者,建议顺着以下路径继续阅读源码:小窗几何从 float_window_geometry.dart 入手,滚动边界看 pure_live_scroll_physics.dart,刷新事务语义读 favorite_controller.dart 与 favorite_startup_policy.dart,字体目录收敛见 app_path_manager.dart,刷新率通道见 display_mode_service.dart。