React组件中如何捕获Vimeo Player.js的视频未找到404错误

针对你遇到的Vimeo Player iframe内部抛出404无法捕获的问题，这里提供三个可行的解决思路，按优先级推荐：

1. 监听Vimeo Player原生error事件 #

Vimeo官方SDK提供了error事件，能直接捕获播放相关错误，其中错误代码22对应"视频不存在或不可访问"的场景。修改你的初始化逻辑，添加事件监听即可：

import Player from '@vimeo/player';
import { useRef, useState, useEffect } from 'react';

function VimeoVideoPlayer({ videoUrl }) {
  const videoPlayerContainer = useRef(null);
  const [showFallback, setShowFallback] = useState(false);

  useEffect(() => {
    if (!videoPlayerContainer.current || showFallback) return;

    const player = new Player(videoPlayerContainer.current, {
      url: videoUrl,
      controls: true,
      responsive: true,
      transparent: false,
      dnt: true,
      color: '327ea5'
    });

    // 监听错误事件，匹配视频不存在的错误码
    player.on('error', (error) => {
      if (error.code === 22) {
        setShowFallback(true);
        player.destroy(); // 销毁播放器避免无效资源加载
      }
    });

    // 组件卸载时清理播放器实例
    return () => player.destroy();
  }, [videoUrl, showFallback]);

  return (
    <>
      {showFallback ? (
        <div className="video-fallback">视频不存在，请检查链接或更换视频</div>
      ) : (
        <div ref={videoPlayerContainer} className="vimeo-player-container" />
      )}
    </>
  );
}

2. 提前校验视频可用性（无API密钥方案） #

如果error事件无法覆盖某些边缘场景，可以提前通过Vimeo的公共API校验视频是否存在。这种方法不需要申请API密钥，但有请求频率限制，适合低并发场景：

// 单独封装校验函数
const checkVimeoVideoExists = async (videoUrl) => {
  try {
    // 从视频URL中提取ID（兼容vimeo.com/xxx和vimeo.com/channels/xxx/xxx格式）
    const videoIdMatch = videoUrl.match(/vimeo\.com\/(?:channels\/[^/]+\/|album\/\d+\/)?(\d+)/);
    if (!videoIdMatch) return false;
    
    const videoId = videoIdMatch[1];
    const response = await fetch(`https://vimeo.com/api/v2/video/${videoId}.json`);
    
    return response.ok;
  } catch (err) {
    console.error('校验视频可用性失败:', err);
    return false;
  }
};

// 在组件中使用
useEffect(() => {
  const initPlayerOrShowFallback = async () => {
    const isVideoValid = await checkVimeoVideoExists(videoUrl);
    if (!isVideoValid) {
      setShowFallback(true);
      return;
    }

    // 校验通过后初始化播放器
    const player = new Player(videoPlayerContainer.current, {
      url: videoUrl,
      controls: true,
      responsive: true,
      transparent: false,
      dnt: true,
      color: '327ea5'
    });

    // 仍保留error事件作为兜底
    player.on('error', (error) => {
      if (error.code === 22) {
        setShowFallback(true);
        player.destroy();
      }
    });
  };

  initPlayerOrShowFallback();
}, [videoUrl]);

3. 监听iframe的加载错误（兜底方案） #

如果前两种方法都不生效，可以直接监听Vimeo生成的iframe的error事件。注意跨域限制可能导致部分浏览器无法捕获详细错误，但可以作为最后的兜底：

useEffect(() => {
  if (!videoPlayerContainer.current) return;

  const player = new Player(videoPlayerContainer.current, {
    url: videoUrl,
    controls: true,
    responsive: true,
    transparent: false,
    dnt: true,
    color: '327ea5'
  });

  // 等待iframe生成后绑定事件
  setTimeout(() => {
    const iframe = videoPlayerContainer.current.querySelector('iframe');
    if (iframe) {
      iframe.addEventListener('error', () => {
        setShowFallback(true);
        player.destroy();
      });
    }
  }, 500);

  return () => player.destroy();
}, [videoUrl]);

关键提示 #

• 优先使用方案1，这是官方支持的错误捕获方式，兼容性最好。
• 方案2适合需要提前判断视频状态、避免加载无效播放器的场景，但要注意请求频率。
• 方案3是兜底，受浏览器跨域策略限制，可能在部分环境下失效。

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