React中iframe嵌入YouTube视频，重播结束无状态变更排查

核心原因 #

你遇到的问题大概率是事件监听的绑定方式不对，分两种常见情况：

1. 若直接给<iframe>标签绑定ended事件：浏览器的跨域限制会导致事件无法持续触发——首次播放结束可能因浏览器临时机制触发，但重播时iframe内部的视频状态变化无法跨域传递到父页面，回调自然失效。
2. 若使用了YouTube Player API，但事件监听仅在初始化时绑定一次，且后续因组件状态变化、Player实例意外重置等原因，监听被间接移除。

解决方案 #

方案一：用YouTube官方Player API（推荐） #

这是最稳定的实现方式，通过API监听onStateChange事件来判断视频结束状态，无论重播多少次都能正常触发回调：

import { useRef, useEffect } from 'react';

const VideoExternal = () => {
  const playerRef = useRef(null);

  useEffect(() => {
    // 加载YouTube Player API（未加载时才注入）
    if (!window.YT) {
      const scriptTag = document.createElement('script');
      scriptTag.src = 'https://www.youtube.com/iframe_api';
      document.body.appendChild(scriptTag);
    }

    // 初始化Player实例
    const initPlayer = () => {
      playerRef.current = new window.YT.Player('youtube-player', {
        videoId: '你的视频ID',
        playerVars: {
          autoplay: 1,
          controls: 1
        },
        events: {
          onStateChange: (event) => {
            // 监听视频结束状态（YT.PlayerState.ENDED对应值为0）
            if (event.data === 0) {
              console.log('Video ended.');
            }
          }
        }
      });
    };

    // 等待API加载完成后初始化
    if (window.YT) {
      initPlayer();
    } else {
      window.onYouTubeIframeAPIReady = initPlayer;
    }

    // 组件卸载时销毁Player，避免内存泄漏
    return () => {
      playerRef.current?.destroy();
    };
  }, []);

  const handleReplay = () => {
    playerRef.current?.playVideo();
  };

  return (
    <div>
      <div id="youtube-player"></div>
      <button onClick={handleReplay}>重播</button>
    </div>
  );
};

export default VideoExternal;

方案二：原生iframe配合postMessage（不推荐，仅适配简单场景） #

如果不想引入官方API，需要在iframe的src中添加enablejsapi=1参数，通过postMessage实现跨域通信监听状态：

import { useRef, useEffect } from 'react';

const VideoExternal = () => {
  const iframeRef = useRef(null);

  useEffect(() => {
    const handleMessage = (event) => {
      // 校验消息来源，避免安全风险
      if (event.origin !== 'https://www.youtube.com') return;
      const data = JSON.parse(event.data);
      // 监听视频结束事件（状态码0对应结束）
      if (data.event === 'onStateChange' && data.data === 0) {
        console.log('Video ended.');
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, []);

  const handleReplay = () => {
    iframeRef.current?.contentWindow.postMessage(
      JSON.stringify({ event: 'command', func: 'playVideo' }),
      'https://www.youtube.com'
    );
  };

  return (
    <div>
      <iframe
        ref={iframeRef}
        src="https://www.youtube.com/embed/你的视频ID?autoplay=1&enablejsapi=1"
        frameBorder="0"
        allow="autoplay; encrypted-media"
        allowFullScreen
      />
      <button onClick={handleReplay}>重播</button>
    </div>
  );
};

export default VideoExternal;

关键注意事项 #

• 绝对不要直接给iframe绑定ended事件，跨域限制会导致回调不可靠。
• 使用官方API时，无需在重播时重新初始化iframe或Player实例，直接调用playVideo()即可。
• 组件卸载时务必销毁Player实例，避免内存泄漏。

内容的提问来源于stack exchange，提问作者Boky