Skip to content

一分钟搭建影视站,支持Docker等部署方式

fix(player): 网页全屏下自动连播黑屏有声——保持 ArtPlayer 常驻、换集只切换 HLS 源

bestZwei3e47cd2ee37a
diff --git a/src/components/player-shell.tsx b/src/components/player-shell.tsx
index 67196c4..1a77fdc 100644
--- a/src/components/player-shell.tsx
+++ b/src/components/player-shell.tsx
@@ -17,6 +17,10 @@ import { formatTime } from '@/lib/utils';
* 播放器外壳:ArtPlayer + hls.js(旧版 player.js 的 React 化)。
* 保留:广告分片过滤、自动连播回调、进度回调、快捷键、移动端长按倍速、错误恢复。
* 移除:DOM 手工操作、watch.html 跳转链、localStorage 状态总线。
+ *
+ * 关键设计:ArtPlayer 实例只在挂载时创建一次,换集(url 变化)只「切换 HLS 源」
+ * 而不销毁重建。否则在「网页全屏(页面全屏)」下整实例重建会丢失全屏上下文、
+ * 重建 <video> 元素,触发「黑屏有声」的渲染竞态。
*/
interface PlayerShellProps {
@@ -61,46 +65,45 @@ export function PlayerShell({
// 起播前的品牌占位图(沿用旧版 nomedia 素材),实际开始播放后隐藏
const [showPoster, setShowPoster] = useState(true);
const hintTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
- // 用 ref 持有最新回调,避免重建播放器
- const cbs = useRef({ onTimeUpdate, onEnded, onPause, getRestorePosition, onRequestSwitchSource });
- cbs.current = { onTimeUpdate, onEnded, onPause, getRestorePosition, onRequestSwitchSource };
- const autoplayRef = useRef(autoplayNext);
- autoplayRef.current = autoplayNext;
- useEffect(() => {
- if (!containerRef.current || !url) return;
- setError('');
- setShowPoster(true);
+ // 始终持有最新 props/回调,避免重建播放器
+ const propsRef = useRef({
+ url, title, adFilter, autoplayNext, episodeKey, nextUrl, nextEpisodeKey,
+ getRestorePosition, onTimeUpdate, onEnded, onPause, onRequestSwitchSource,
+ });
+ propsRef.current = {
+ url, title, adFilter, autoplayNext, episodeKey, nextUrl, nextEpisodeKey,
+ getRestorePosition, onTimeUpdate, onEnded, onPause, onRequestSwitchSource,
+ };
- // 换集时清理函数在「新回调已挂到 ref 上」之后才执行,
- // 卸载前保存进度必须用本次挂载(本集)的回调,否则会把上一集的
- // 播放位置写进新集数的进度记录,导致换集后从上一集的时间点继续播放
- const mountCbs = { onTimeUpdate, onEnded, onPause, getRestorePosition };
+ // 跨集共享、每次换集重置的播放链路状态
+ // 媒体健康度:音频轨可播不代表视频轨正常(「黑屏但有声」的假死态)。
+ // 仅当有分片真正进入 MSE buffer 后才视为恢复,错误遮罩才能被清除。
+ const mediaHealthyRef = useRef(true);
+ const playbackStartedRef = useRef(false);
+ // 起播阶段的 video 元素级错误允许自愈重试一次(重建 hls/MSE)
+ const videoErrorRetryUsedRef = useRef(false);
+ // 进度恢复每集只执行一次(MANIFEST_PARSED 可能因代理回退再次触发)
+ const restoredRef = useRef(false);
+ // setupHls 可能改走代理形式,video:error 重试要用最近一次的地址
+ const currentMediaUrlRef = useRef(url);
+ // 本集的恢复策略实例:跨直连/代理两级重建共享计数
+ const recoveryRef = useRef<PlaybackRecovery | null>(null);
+ // 自然播完标记,卸载时不回写进度(避免覆盖「已看完」记录)
+ const endedRef = useRef(false);
- let lastSave = 0;
- let lastPrefetchEnsure = 0;
- let playbackStarted = false;
- let ended = false;
- // 媒体健康度:音频轨可播不代表视频轨正常(「黑屏但有声」的假死态)。
- // 仅当有分片真正进入 MSE buffer 后才视为恢复,错误遮罩才能被清除。
- let mediaHealthy = true;
- // 起播阶段的 video 元素级错误允许自愈重试一次(重建 hls/MSE)
- let videoErrorRetryUsed = false;
- // setupHls 可能改走代理形式,video:error 重试要用最近一次的地址
- let currentMediaUrl = url;
- // 本集的恢复策略实例:跨直连/代理两级重建共享计数,换集随 effect 重建
- const recovery = new PlaybackRecovery();
+ const showHint = (text: string) => {
+ setHint(text);
+ if (hintTimerRef.current) clearTimeout(hintTimerRef.current);
+ hintTimerRef.current = setTimeout(() => setHint(''), 2500);
+ };
- const showHint = (text: string) => {
- setHint(text);
- if (hintTimerRef.current) clearTimeout(hintTimerRef.current);
- hintTimerRef.current = setTimeout(() => setHint(''), 2500);
- };
-
- // 片段缓存开启时调大 hls.js 自身缓冲,缓冲之外的空窗由预取器补齐
+ // 片段缓存开启时调大 hls.js 自身缓冲,缓冲之外的空窗由预取器补齐
+ const buildHlsConfig = (): Partial<HlsConfig> => {
+ const p = propsRef.current;
const cacheSettings = loadCacheSettings();
- const cacheEnabled = cacheSettings.enabled && !!episodeKey;
- const hlsConfig: Partial<HlsConfig> = {
+ const cacheEnabled = cacheSettings.enabled && !!p.episodeKey;
+ return {
debug: false,
enableWorker: true,
backBufferLength: 90,
@@ -116,102 +119,152 @@ export function PlayerShell({
abrEwmaDefaultEstimate: 500_000,
appendErrorMaxRetry: 5,
// 组合 loader:广告过滤(blockAd 随设置)+ 片段缓存命中(cacheEnabled)
- loader: createHlsLoader(Hls, { blockAd: adFilter }) as unknown as HlsConfig['loader'],
- };
-
- /**
- * 初始化 HLS。allowProxyFallback:直连致命网络错误(CORS/防盗链/分片被拒)时,
- * 自动改走同源 cookie 鉴权的 /api/proxy 重试一次。
- */
- // 当前集预取(episodeKey 缺省 = 关闭,见 ensure 内部 settings.enabled 判断)
- const ensurePrefetch = (mediaUrl: string, currentTime: number, horizonSeconds?: number) => {
- if (!episodeKey) return;
- getVideoPrefetcher().ensure({
- m3u8Url: mediaUrl,
- currentTime,
- episodeKey,
- horizonSeconds,
- onProgress: (stats) => {
- // 当前集预取完成且存在下一集:用独立预取器预热下一集前 7 分钟
- if (stats.state === 'done' && nextUrl && nextEpisodeKey) {
- getNextEpisodePrefetcher().ensure({
- m3u8Url: nextUrl,
- currentTime: 0,
- episodeKey: nextEpisodeKey,
- horizonSeconds: 420,
- });
- }
- },
- });
+ loader: createHlsLoader(Hls, { blockAd: p.adFilter }) as unknown as HlsConfig['loader'],
};
+ };
- const setupHls = (video: HTMLVideoElement, mediaUrl: string, allowProxyFallback: boolean) => {
- hlsRef.current?.destroy();
- currentMediaUrl = mediaUrl;
- const hls = new Hls(hlsConfig);
- hlsRef.current = hls;
+ // 当前集预取(episodeKey 缺省 = 关闭,见 ensure 内部 settings.enabled 判断)
+ const ensurePrefetch = (mediaUrl: string, currentTime: number, horizonSeconds?: number) => {
+ const p = propsRef.current;
+ if (!p.episodeKey) return;
+ getVideoPrefetcher().ensure({
+ m3u8Url: mediaUrl,
+ currentTime,
+ episodeKey: p.episodeKey,
+ horizonSeconds,
+ onProgress: (stats) => {
+ // 当前集预取完成且存在下一集:用独立预取器预热下一集前 7 分钟
+ if (stats.state === 'done' && p.nextUrl && p.nextEpisodeKey) {
+ getNextEpisodePrefetcher().ensure({
+ m3u8Url: p.nextUrl,
+ currentTime: 0,
+ episodeKey: p.nextEpisodeKey,
+ horizonSeconds: 420,
+ });
+ }
+ },
+ });
+ };
- hls.loadSource(mediaUrl);
- hls.attachMedia(video);
+ /**
+ * 初始化/切换 HLS。allowProxyFallback:直连致命网络错误(CORS/防盗链/分片被拒)时,
+ * 自动改走同源 cookie 鉴权的 /api/proxy 重试一次。
+ * 注意:不销毁 ArtPlayer,只销毁并重建 hls,从而保留网页全屏等播放器状态。
+ */
+ const setupHls = (video: HTMLVideoElement, mediaUrl: string, allowProxyFallback: boolean) => {
+ hlsRef.current?.destroy();
+ currentMediaUrlRef.current = mediaUrl;
+ const hls = new Hls(buildHlsConfig());
+ hlsRef.current = hls;
- hls.on(Hls.Events.MANIFEST_PARSED, () => {
- recovery.markHealthy();
- video.play().catch(() => {});
- });
- // 播放链路恢复(FRAG_LOADED / MANIFEST_PARSED):静默窗外清零连续失败计数
- hls.on(Hls.Events.FRAG_LOADED, () => recovery.markHealthy());
- // 分片真正进入 MSE buffer 才算媒体恢复:此时视频轨可渲染,错误态可解除
- hls.on(Hls.Events.FRAG_BUFFERED, () => {
- mediaHealthy = true;
- });
+ hls.loadSource(mediaUrl);
+ hls.attachMedia(video);
- hls.on(Hls.Events.ERROR, (_evt, data) => {
- if (!data.fatal) return;
- const decision = recovery.onFatal(data.type, data.details);
- switch (decision.action) {
- case 'ignore':
- break;
- case 'retry': {
- // 前两次重试保留直连;达到退避阈值或清单级错误时升级为代理形式
- // (同源 cookie 鉴权,规避 CORS/防盗链/分片被拒)
- if (
- allowProxyFallback &&
- !mediaUrl.startsWith('/api/proxy') &&
- (decision.attempt >= 2 || data.details === 'manifestLoadError')
- ) {
- showHint('直连失败,改用代理重试...');
- setupHls(video, `/api/proxy?url=${encodeURIComponent(mediaUrl)}`, false);
- return;
- }
- showHint(`${decision.reason}(第 ${decision.attempt} 次)...`);
- recovery.schedule(decision.delayMs, () => hls.startLoad());
- break;
+ hls.on(Hls.Events.MANIFEST_PARSED, async () => {
+ recoveryRef.current?.markHealthy();
+ // 进度恢复(每集一次):优先 URL position,其次 IndexedDB 记录
+ if (!restoredRef.current) {
+ restoredRef.current = true;
+ try {
+ const saved = (await propsRef.current.getRestorePosition?.()) ?? 0;
+ const duration = artRef.current?.duration || 0;
+ if (saved > 10 && duration > 0 && saved < duration - 2) {
+ if (artRef.current) artRef.current.currentTime = saved;
+ showHint(`已从 ${formatTime(saved)} 继续播放`);
}
- case 'recover-media': {
- showHint(`${decision.reason}(第 ${decision.attempt} 次)...`);
- if (decision.swapAudio) hls.swapAudioCodec?.();
- hls.recoverMediaError();
- break;
+ } catch { /* 忽略恢复失败 */ }
+ }
+ video.play().catch(() => {});
+ });
+ // 播放链路恢复(FRAG_LOADED / MANIFEST_PARSED):静默窗外清零连续失败计数
+ hls.on(Hls.Events.FRAG_LOADED, () => recoveryRef.current?.markHealthy());
+ // 分片真正进入 MSE buffer 才算媒体恢复:此时视频轨可渲染,错误态可解除
+ hls.on(Hls.Events.FRAG_BUFFERED, () => {
+ mediaHealthyRef.current = true;
+ });
+
+ hls.on(Hls.Events.ERROR, (_evt, data) => {
+ if (!data.fatal) return;
+ const recovery = recoveryRef.current;
+ if (!recovery) return;
+ const decision = recovery.onFatal(data.type, data.details);
+ switch (decision.action) {
+ case 'ignore':
+ break;
+ case 'retry': {
+ // 前两次重试保留直连;达到退避阈值或清单级错误时升级为代理形式
+ // (同源 cookie 鉴权,规避 CORS/防盗链/分片被拒)
+ if (
+ allowProxyFallback &&
+ !mediaUrl.startsWith('/api/proxy') &&
+ (decision.attempt >= 2 || data.details === 'manifestLoadError')
+ ) {
+ showHint('直连失败,改用代理重试...');
+ setupHls(video, `/api/proxy?url=${encodeURIComponent(mediaUrl)}`, false);
+ return;
}
- case 'switch-source': {
- // 覆盖播放开始后的场景:起播失败走 setError 遮罩;
- // 播放中失败走回调弹换源面板(父级未提供回调时同样 setError)
- const message = `${describeHlsError(data.type, data.details)}:${decision.reason}`;
- if (playbackStarted) {
- showHint(message);
- cbs.current.onRequestSwitchSource?.(decision.reason);
- } else {
- setError(`视频加载失败,${message},请尝试其他视频源`);
- }
- break;
+ showHint(`${decision.reason}(第 ${decision.attempt} 次)...`);
+ recovery.schedule(decision.delayMs, () => hls.startLoad());
+ break;
+ }
+ case 'recover-media': {
+ showHint(`${decision.reason}(第 ${decision.attempt} 次)...`);
+ if (decision.swapAudio) hls.swapAudioCodec?.();
+ hls.recoverMediaError();
+ break;
+ }
+ case 'switch-source': {
+ // 覆盖播放开始后的场景:起播失败走 setError 遮罩;
+ // 播放中失败走回调弹换源面板(父级未提供回调时同样 setError)
+ const message = `${describeHlsError(data.type, data.details)}:${decision.reason}`;
+ if (playbackStartedRef.current) {
+ showHint(message);
+ propsRef.current.onRequestSwitchSource?.(decision.reason);
+ } else {
+ setError(`视频加载失败,${message},请尝试其他视频源`);
}
+ break;
}
- });
- };
+ }
+ });
+ };
+
+ /** 换集:重置每集状态并切换到新 HLS 源(不重建 ArtPlayer)。 */
+ const loadEpisode = (targetUrl: string) => {
+ if (!targetUrl) return;
+ mediaHealthyRef.current = true;
+ playbackStartedRef.current = false;
+ videoErrorRetryUsedRef.current = false;
+ restoredRef.current = false;
+ recoveryRef.current = new PlaybackRecovery();
+ // 换集时清掉上一集的预取窗口,避免带宽被旧集占用
+ getVideoPrefetcher().stop();
+ setError('');
+ setShowPoster(true);
+ const art = artRef.current;
+ if (!art) return;
+ setupHls(art.video, targetUrl, true);
+ };
+
+ // —— 创建播放器(仅一次,挂载即创建) ——
+ useEffect(() => {
+ if (!containerRef.current || !propsRef.current.url) return;
+ const initialUrl = propsRef.current.url;
+
+ // 初始化每集状态
+ mediaHealthyRef.current = true;
+ playbackStartedRef.current = false;
+ videoErrorRetryUsedRef.current = false;
+ restoredRef.current = false;
+ recoveryRef.current = new PlaybackRecovery();
+ endedRef.current = false;
+
+ let lastSave = 0;
+ let lastPrefetchEnsure = 0;
const art = new Artplayer({
container: containerRef.current,
- url,
+ url: initialUrl,
type: 'm3u8',
volume: 0.8,
autoplay: true,
@@ -243,38 +296,25 @@ export function PlayerShell({
// ArtPlayer 运行时支持 title 选项(类型定义未覆盖),用于界面标题展示
try {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
- (art as any).title = title;
+ (art as any).title = propsRef.current.title;
} catch { /* 忽略 */ }
});
- art.on('ready', () => {
- // 进度恢复
- const restore = async () => {
- const saved = (await cbs.current.getRestorePosition?.()) ?? 0;
- const duration = art.duration || 0;
- if (saved > 10 && duration > 0 && saved < duration - 2) {
- art.currentTime = saved;
- showHint(`已从 ${formatTime(saved)} 继续播放`);
- }
- };
- restore();
- });
-
art.on('video:playing', () => {
- playbackStarted = true;
+ playbackStartedRef.current = true;
setShowPoster(false);
// 仅在媒体真正恢复(有分片进入 buffer)后清错误遮罩:
// 否则「视频轨挂了、音频轨先播出来」时会清掉遮罩,留下黑屏假死态
- if (mediaHealthy) setError('');
+ if (mediaHealthyRef.current) setError('');
});
art.on('video:error', () => {
- mediaHealthy = false;
+ mediaHealthyRef.current = false;
// 起播阶段的 video 元素级错误(MSE/解码偶发失败):重建一次播放链路自愈,
// 而不是直接钉死错误遮罩——重建后视频轨重新 append,黑屏有声即可解除
- if (!playbackStarted && !videoErrorRetryUsed) {
- videoErrorRetryUsed = true;
+ if (!playbackStartedRef.current && !videoErrorRetryUsedRef.current) {
+ videoErrorRetryUsedRef.current = true;
showHint('播放异常,正在重试...');
- setupHls(art.video, currentMediaUrl, true);
+ setupHls(art.video, currentMediaUrlRef.current, true);
return;
}
setError('视频播放失败,请尝试其他视频源');
@@ -283,21 +323,21 @@ export function PlayerShell({
const now = Date.now();
if (now - lastSave > 5000) {
lastSave = now;
- cbs.current.onTimeUpdate?.(art.currentTime, art.duration);
+ propsRef.current.onTimeUpdate?.(art.currentTime, art.duration);
}
// 每 30s 续跑一次前向预取窗口(ensure 幂等,窗口未覆盖足够余量才会重建)
if (now - lastPrefetchEnsure > 30_000) {
lastPrefetchEnsure = now;
- ensurePrefetch(url, art.currentTime);
+ ensurePrefetch(propsRef.current.url, art.currentTime);
}
});
art.on('video:seeked', () => {
- ensurePrefetch(url, art.currentTime);
+ ensurePrefetch(propsRef.current.url, art.currentTime);
});
art.on('video:pause', () => {
- cbs.current.onPause?.(art.currentTime, art.duration);
+ propsRef.current.onPause?.(art.currentTime, art.duration);
// 暂停 = 预取黄金窗口:解除限速并无限铺满整集(用户主动行为,带宽占用可接受)
- ensurePrefetch(url, art.currentTime, 0);
+ ensurePrefetch(propsRef.current.url, art.currentTime, 0);
});
art.on('video:waiting', () => {
// 卡顿:预取临时让出带宽给播放
@@ -307,8 +347,8 @@ export function PlayerShell({
getVideoPrefetcher().setThrottled(false);
});
art.on('video:ended', () => {
- ended = true;
- cbs.current.onEnded?.();
+ endedRef.current = true;
+ propsRef.current.onEnded?.();
});
// —— 键盘快捷键(旧版 hotkey:false + 自定义逻辑的移植) ——
@@ -376,23 +416,20 @@ export function PlayerShell({
el?.addEventListener('touchcancel', onTouchEnd);
el?.addEventListener('touchmove', onTouchMove, { passive: false });
- // 双击全屏由 ArtPlayer 原生 DBCLICK_FULLSCREEN 处理(video:dblclick 不在其事件代理列表中,监听无效)
-
// 卸载与页面隐藏时保存进度
const saveOnHide = () => {
if (document.visibilityState === 'hidden') {
- cbs.current.onPause?.(art.currentTime, art.duration);
+ propsRef.current.onPause?.(art.currentTime, art.duration);
}
};
document.addEventListener('visibilitychange', saveOnHide);
return () => {
// 卸载前刷一次最终进度,避免丢失最后几秒。
- // 注意用 mountCbs(本集回调)而非 cbs.current(已是下一集的回调);
// 已自然播完的集数不回写,避免覆盖 onEnded 里清除的「已看完」记录
- if (!ended) {
+ if (!endedRef.current) {
try {
- mountCbs.onPause?.(art.currentTime, art.duration);
+ propsRef.current.onPause?.(art.currentTime, art.duration);
} catch { /* 忽略 */ }
}
document.removeEventListener('keydown', shortcuts);
@@ -404,13 +441,30 @@ export function PlayerShell({
el?.removeEventListener('touchmove', onTouchMove);
hlsRef.current?.destroy();
hlsRef.current = null;
- recovery.dispose();
+ recoveryRef.current?.dispose();
getVideoPrefetcher().stop();
art.destroy();
artRef.current = null;
};
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [url, adFilter]);
+ }, []);
+
+ // —— 换集:仅切换 HLS 源,不重建播放器(保留网页全屏等状态) ——
+ const firstUrlRef = useRef(true);
+ useEffect(() => {
+ // 挂载时的首次由创建 effect 的 customType 触发,跳过避免重复加载
+ if (firstUrlRef.current) { firstUrlRef.current = false; return; }
+ loadEpisode(url);
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [url]);
+
+ // —— 广告过滤开关变化:重建 HLS loader(无需重建整个播放器) ——
+ const firstAdFilterRef = useRef(true);
+ useEffect(() => {
+ if (firstAdFilterRef.current) { firstAdFilterRef.current = false; return; }
+ if (artRef.current && hlsRef.current) loadEpisode(propsRef.current.url);
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [adFilter]);
return (
<div className="relative w-full h-full">