自定义React音频播放器初始播放需两次点击按钮问题排查

我开发了一个基于React/Vite的简易音频播放器，支持自动或手动切换至下一曲目。播放器功能正常，但存在初始播放异常：页面加载时显示的是暂停按钮，需先点击暂停按钮切换为播放按钮，再点击播放按钮才能启动音频播放。从代码逻辑来看，初始加载时应显示播放按钮，但我无法定位问题根源，已花费两个下午排查，恳请技术帮助。

AwesomeDrummers组件 #

const AwesomeDrummers = (props) => {
  return (
    <section>
      <div>
        <h2 className="section-title">Awesome Drummers</h2>
        <AudioPlayer stories={props} />
      </div>
    </section>
  );
};

AudioPlayer组件 #

const AudioPlayer = ({ stories }) => {
  const [textIndex, settextIndex] = useState(0);
  const [isPlaying, setIsPlaying] = useState(false);

  const { text, audioSrc } = stories.stories[textIndex];

  const audioRef = useRef(new Audio(audioSrc));
  const intervalRef = useRef();
  const isReady = useRef(false);

  const startTimer = () => {
    // Clear any running timers
    clearInterval(intervalRef.current);

    intervalRef.current = setInterval(() => {
      if (audioRef.current.ended) {
        toNexttext();
      }
    }, 1000);
  };

  const toPrevtext = () => {
    if (textIndex - 1 < 0) {
      settextIndex(stories.stories.length - 1);
    } else {
      settextIndex(textIndex - 1);
    }
  };

  const toNexttext = () => {
    if (textIndex < stories.stories.length - 1) {
      settextIndex(textIndex + 1);
    } else {
      settextIndex(0);
    }
  };

  useEffect(() => {
    if (isPlaying) {
      audioRef.current.play();
      startTimer();
    } else {
      audioRef.current.pause();
    }
  }, [isPlaying]);

  // Cleanup when story changes
  useEffect(() => {
    audioRef.current.pause();

    audioRef.current = new Audio(audioSrc);

    if (isReady.current) {
      audioRef.current.play();
      setIsPlaying(true);
      startTimer();
    } else {
      // true = next pass
      isReady.current = true;
    }
  }, [textIndex]);

  useEffect(() => {
    // Pause and clean up on unmount
    return () => {
      audioRef.current.pause();
      clearInterval(intervalRef.current);
    };
  }, []);

  return (
    <>
      <div className="center-container">
        <div className="text-container">
          <p className="text-areas">{text}</p>
        </div>
      </div>
      <div>
        <AudioControls isPlaying={isPlaying} onPrevClick={toPrevtext} onNextClick={toNexttext} onPlayPauseClick={setIsPlaying} />
      </div>
    </>
  );
};

AudioControls组件 #

const AudioControls = ({ isPlaying, onPlayPauseClick, onPrevClick, onNextClick }) => {
  return (
    <div className="audio-controls">
      <button type="button" className="prev" onClick={onPrevClick} aria-label="Previous">
        <BsChevronLeft />
      </button>
      {isPlaying ? (
        <button type="button" className="pause" onClick={() => onPlayPauseClick(false)} aria-label="Pause">
          <FaPause />
        </button>
      ) : (
        <button type="button" className="play" onClick={() => onPlayPauseClick(true)} aria-label="Play">
          <FaPlay />
        </button>
      )}

      <button type="button" className="next" onClick={onNextClick} aria-label="Next">
        <BsChevronRight />
      </button>
    </div>
  );
};

问题根源 #

问题出在AudioPlayer组件中依赖textIndex的useEffect，结合React严格模式（Vite默认在开发环境启用）的特性：

• React严格模式会在开发环境下重复执行挂载阶段的useEffect两次，用于检测副作用问题。
• 第一次执行该useEffect时，isReady.current被设置为true；第二次执行时，isReady.current已经是true，于是触发setIsPlaying(true)，将播放状态强制设为true，导致按钮显示为暂停样式。
• 同时，浏览器的自动播放策略会阻止audioRef.current.play()的自动执行（未经过用户交互的自动播放会被拒绝），这就导致状态显示为播放（暂停按钮），但实际音频并未播放，出现矛盾的异常现象。

解决方案 #

方案1：调整isReady逻辑，处理播放失败情况

修改依赖textIndex的useEffect，确保播放失败时同步状态，避免显示异常：

// Cleanup when story changes
useEffect(() => {
  audioRef.current.pause();

  audioRef.current = new Audio(audioSrc);

  if (isReady.current) {
    // 捕获播放失败的情况，同步状态
    audioRef.current.play()
      .then(() => setIsPlaying(true))
      .catch(() => setIsPlaying(false));
    startTimer();
  } else {
    isReady.current = true;
  }
}, [textIndex]);

方案2：移除初始自动播放逻辑（更简单直接）

如果不需要切换曲目时自动播放，直接去掉isReady相关逻辑，完全由用户手动控制播放：

// Cleanup when story changes
useEffect(() => {
  audioRef.current.pause();
  audioRef.current = new Audio(audioSrc);
  // 移除自动播放和setIsPlaying逻辑
}, [textIndex]);

额外优化：全局处理播放状态

修改监听isPlaying的useEffect，统一处理播放失败的情况：

useEffect(() => {
  if (isPlaying) {
    audioRef.current.play()
      .catch(() => {
        // 播放失败时重置状态为暂停
        setIsPlaying(false);
      });
    startTimer();
  } else {
    audioRef.current.pause();
  }
}, [isPlaying]);

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