React+TypeScript项目使用YouTube iframe API的YT对象构建报错解决

方法1：安装官方类型定义包 #

直接安装YouTube API的TypeScript类型包，这是最省心的方式：

npm install @types/youtube --save-dev
# 或使用yarn
yarn add @types/youtube --dev

安装完成后，TypeScript会自动识别全局的YT对象及其所有类型，无需额外配置。

方法2：手动声明全局类型 #

如果不想安装额外包，可以在项目中创建一个类型声明文件（比如src/types/youtube.d.ts），手动定义YT的类型：

// src/types/youtube.d.ts
declare global {
  namespace YT {
    class Player {
      constructor(elementId: string, options: PlayerOptions);
      playVideo(): void;
      pauseVideo(): void;
      stopVideo(): void;
      // 按需添加Player的其他方法
    }

    interface PlayerOptions {
      videoId?: string;
      height?: string | number;
      width?: string | number;
      events?: {
        onReady?: (event: { target: Player }) => void;
        onStateChange?: (event: { data: number; target: Player }) => void;
        onError?: (event: { data: number; target: Player }) => void;
      };
      // 按需添加其他配置项
    }
  }
}

export {};

确保TypeScript能识别这个声明文件（检查tsconfig.json中include字段是否包含src/types/**/*）。

方法3：确保脚本加载完成后再使用YT对象 #

除了类型问题，还要注意脚本加载是异步的，避免运行时出现YT is undefined的错误。可以修改useEffect代码，监听脚本加载完成事件：

import { useState, useEffect } from 'react';

// 组件内状态
const [scriptLoaded, setScriptLoaded] = useState(false);

useEffect(() => {
  const tag = document.createElement('script');
  tag.src = "https://www.youtube.com/iframe_api";
  tag.onload = () => {
    setScriptLoaded(true);
  };
  const firstScriptTag = document.getElementsByTagName('script')[0];
  const scriptContainer = document.head || document.documentElement;
  
  if (firstScriptTag) {
    scriptContainer.insertBefore(tag, firstScriptTag);
  } else {
    scriptContainer.appendChild(tag);
  }

  // 组件卸载时清理脚本
  return () => tag.remove();
}, []);

// 仅在脚本加载完成后执行初始化逻辑
async function all_api_requests_finished(): Promise<void> {
  if (!scriptLoaded) return;
  
  num_vids = unshuffled_video_ids.length;
  shuffled_video_ids = shuffle(unshuffled_video_ids);

  player = new YT.Player('player', {
    videoId: shuffled_video_ids[curr_vid],
    height: '390',
    width: '640',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError,
    }
  });
  player_loaded = true;
}

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