草原指南切换 2x 后永久缓冲更正

日期：2026-07-16

前端仓库：mmg/hl-ui

影响组件：src/views/h5/grassland-guide/components/GuideVideoPlayer.vue

影响辅助逻辑：src/views/h5/grassland-guide/components/playbackBuffer.js

本次后端接口、字段、OSS 地址和视频文件均无变化

1. 现象

视频在 1x 已经开始播放后切换到 2x，页面停在“正在缓冲”，即使等待较长时间也不能恢复。

Network 中可以看到同一个 MP4 存在多条大小不同的 206 Partial Content 请求。这是 Chrome 原生媒体加载器根据 MP4 元数据、当前播放位置和缓存状态发起的 HTTP Range 请求，Range 大小不固定是正常行为，不能据此判断 OSS 分片异常。

2. 已确认根因

线上播放器当前调用链为：

切换 2x
  → 设置 video.playbackRate = 2
  → evaluateBuffer({ initial: true })
  → 要求 bufferAhead >= 15 秒
  → 未达到阈值
  → pauseForBuffering()
  → video.pause()

播放器暂停后，浏览器可以降低甚至停止后续媒体预取。当前代码又只依赖 progress、canplay 等媒体事件重新执行 evaluateBuffer()，没有保证这些事件一定继续产生，因此可能永远达不到 15 秒阈值，形成状态机死锁。

同类问题还存在于：

首次播放前等待固定 8 秒。
timeupdate 检测到低水位后主动 pause()。
waiting/stalled 事件再次主动 pause()。

这些逻辑把浏览器原生的“缺数据时等待并继续下载”变成了应用层“暂停后等待浏览器继续下载”，两者行为并不等价。

3. 必须修改的前端逻辑

3.1 播放与切换倍速

async function play() {
  playbackRequested.value = true
  await videoRef.value?.play()
}

function togglePlaybackRate() {
  const video = videoRef.value
  if (!video) return

  playbackRate.value = playbackRate.value === 1 ? 2 : 1
  video.playbackRate = playbackRate.value

  // 禁止在这里 pause()
  // 禁止在这里重新执行固定秒数的初始缓冲门槛
}

3.2 缓冲状态由原生事件驱动

function handleWaiting() {
  if (!playbackRequested.value) return
  buffering.value = true
  recordPlaybackEvent('waiting')
}

function handleStalled() {
  const video = videoRef.value
  if (playbackRequested.value && video?.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
    buffering.value = true
  }
  recordPlaybackEvent('stalled')
}

function handlePlaying() {
  buffering.value = false
  recordPlaybackEvent('playing')
}

事件处理器内不得调用 video.pause()。只要用户没有主动暂停，就保留原生播放意图，让浏览器在缺数据时自动等待、继续 Range 取流，并在数据恢复后自行继续播放。

3.3 删除主动低水位暂停

删除 pauseForBuffering() 对自动缓冲流程的使用。
handleTimeUpdate() 只同步时间、记录 bufferAhead 和掉帧指标，不得检测低水位后暂停。
evaluateBuffer() 不再阻塞首次播放或倍速切换；如保留该方法，只能用于诊断，不能控制 play/pause。
删除 BUFFER_POLICIES 中作为播放硬门槛的 initial/low/resume，避免后续重新引入死锁。

4. 验收要求

1x 点击播放后能直接进入原生播放流程，不等待固定 8 秒。
播放中切换 2x 不触发 pause 事件。
切换 2x 后，即使触发 waiting，后续 Range 请求仍继续。
数据恢复后触发 playing，缓冲遮罩自动消失，播放继续。
1x ↔ 2x 连续切换 10 次，不出现永久缓冲。
拖动进度后仍可重新播放，用户主动暂停不会被自动恢复。
Console 中不再出现 ratechange → initial-buffering → pause 的调用序列。
使用 DevTools 测试真实用户表现时关闭 Disable cache；需要模拟弱网时单独选择网络限速，不把禁用缓存结果当作正常生产表现。

修复状态机后，若 1x 或 2x 仍出现能够自行恢复的短时 waiting，再根据 bufferAhead、实际下载速度和掉帧数判断是用户网络还是设备解码能力问题。播放器逻辑修复不能提高用户带宽；需要跨地区稳定承载原始 4K 高码率视频时，应另行评估 OSS 前置 CDN Range 缓存。

4.3 KiB 原始文件 Blame 文件历史 Unescape Escape