Next.js从v8升级到v10后react-player在iOS端音频播放回调异常

架构老林

2026-9-23

问题根因

基础逻辑偏差：音频播放完成默认触发的是onEnded回调，仅用户手动暂停、代码主动调用暂停接口才会触发onPause。你当前仅绑定了onPause回调，旧版本react-player内部做了兼容，播放结束时会额外触发onPause，该兼容逻辑在iOS环境下失效。
iPhone端独有适配问题：

iPhone上所有浏览器均使用WebKit内核，对HTML5音频事件的触发规则与Chromium内核不同，当播放器尺寸被设置为极小值、或未开启音频预加载时，部分事件回调会被系统拦截。
你使用的react-player v1.6.6存在已知iOS适配缺陷，未正确将原生音频的ended事件绑定到组件的onEnded回调上。

解决方案

补全回调绑定：同时绑定onEnded和onPause到同一个结束处理逻辑，抹平端差异，同时新增preload属性解决iOS音频状态监听异常：

<ReactPlayer
     id='soundPlayer'
     height='1px'
     width='1px'
     ref={this.ref}
     playing={playing}
     volume={1}
     url={file}
     onPlay={this.onPlay}
     onPause={this.handlePlayStop} // 原有暂停逻辑迁移到公共方法handlePlayStop
     onEnded={this.handlePlayStop} // 新增播放结束回调绑定
     onProgress={this.onProgress}
     onDuration={this.onDuration}
     playsinline={true}
     preload="auto" // 新增预加载配置
     file='forceAudio'/>

新增兜底逻辑：在onProgress回调中添加播放进度判断，避免极端情况下回调丢失：

onProgress = (progress) => {
  // 保留原有进度处理逻辑
  if (this.state.duration && progress.played >= 0.99) {
    // 进度接近总时长时主动触发结束逻辑
    this.handlePlayStop()
  }
}