NextJS信使应用中wavesurfer.js重复渲染<wave>元素问题排查

• 组件重复初始化未清理
  检查useEffect的依赖项是否合理，如果依赖项频繁变化，会导致wavesurfer多次初始化。另外必须在清理函数中销毁实例，避免残留：

  useEffect(() => {
    const wavesurfer = WaveSurfer.create({
      container: '#waveform',
    });
    // 组件卸载/依赖更新时销毁实例
    return () => wavesurfer.destroy();
  }, []); // 仅挂载时执行，按需添加必要依赖
  

• SSR/客户端Hydrate冲突
  NextJS的服务端渲染会在客户端hydrate阶段再次执行组件逻辑，容易导致wavesurfer在两端各初始化一次。解决办法是限制仅在客户端初始化：

  useEffect(() => {
    // 确保只在浏览器环境执行
    if (typeof window === 'undefined') return;
    const wavesurfer = WaveSurfer.create({
      container: '#waveform',
    });
    return () => wavesurfer.destroy();
  }, []);
  

  也可以用动态导入禁用SSR：

  import dynamic from 'next/dynamic';
  const Waveform = dynamic(() => import('./Waveform'), { ssr: false });
  

• 选择器匹配多个DOM元素
  如果用类选择器（比如.waveform）作为容器，页面中多个同类别元素会被wavesurfer逐个初始化，生成多个。改用唯一ID或者动态生成的标识：

  <div id={`wave-${uniqueId}`}></div>
  // 初始化时指定唯一容器
  const wavesurfer = WaveSurfer.create({
    container: `#wave-${uniqueId}`,
  });
  

• 状态更新触发重复渲染
  组件状态更新时会重新渲染，如果每次渲染都新建wavesurfer实例，就会产生冗余元素。用useRef存储实例，避免重复创建：

  const wavesurferRef = useRef(null);
  useEffect(() => {
    if (!wavesurferRef.current) {
      wavesurferRef.current = WaveSurfer.create({
        container: '#waveform',
      });
    }
    return () => {
      wavesurferRef.current?.destroy();
      wavesurferRef.current = null;
    };
  }, []);
  

• 业务逻辑重复调用初始化
  检查TTS回调、消息列表更新等逻辑，是否存在重复触发wavesurfer初始化的情况。可以加个初始化标记，确保只执行一次：

  const [initialized, setInitialized] = useState(false);
  useEffect(() => {
    if (initialized) return;
    const wavesurfer = WaveSurfer.create({
      container: '#waveform',
    });
    setInitialized(true);
    return () => wavesurfer.destroy();
  }, [initialized]);
  

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