Next.js 14中使用Spline时出现无限WebGL帧缓冲操作警告

问题情况 #

在Next.js项目中使用@splinetool/react-spline组件渲染3D场景时，进入对应页面会触发无限循环的WebGL警告：

[.WebGL-00003D440AA60E00] GL_INVALID_FRAMEBUFFER_OPERATION: Framebuffer is incomplete: Attachment has zero size.

该警告会刷满控制台，但不会影响Spline场景的功能和应用性能，移除Spline组件后警告消失。

成因分析 #

这个警告的核心是WebGL无法创建有效的帧缓冲区，根源在于渲染Spline的父容器存在尺寸异常：

• 父容器使用hidden xl:block类，在屏幕宽度小于xl断点时处于隐藏状态（display: none），此时Spline组件尝试初始化WebGL场景，但容器没有实际宽高，导致帧缓冲区附件尺寸为0，触发警告。
• 即使在xl断点下容器显示，absolute定位加上scale-75的变换可能导致组件初始化时尺寸计算延迟，进而引发重复警告。

修复方案 #

1. 仅在容器可见时渲染Spline #

通过媒体查询监听屏幕尺寸，只有当屏幕宽度达到xl断点时才渲染Spline组件，避免在隐藏容器中初始化WebGL：

import Spline from "@splinetool/react-spline";
import { useState, useEffect } from 'react';

// 自定义监听xl断点的hook
function useIsXlScreen() {
  const [isXl, setIsXl] = useState(false);
  
  useEffect(() => {
    const mediaQuery = window.matchMedia('(min-width: 1280px)');
    setIsXl(mediaQuery.matches);
    
    const handleChange = (e) => setIsXl(e.matches);
    mediaQuery.addEventListener('change', handleChange);
    
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);
  
  return isXl;
}

export default function LandingFeatureSection() {
  const isXlScreen = useIsXlScreen();
  
  return (
    <section className="container flex flex-col my-20">
      {/* 其他内容 */}
      <motion.div
        initial="hide"
        whileInView="show"
        viewport={{ once: true }}
        variants={fadeRightVariant(0.5, 0.5)}
        className="flex flex-col items-center md:items-start relative w-full lg:px-4 xl:px-16 pb-20 lg:pb-0"
      >
        <div className="hidden xl:block absolute -top-16 -right-20 scale-75">
          {isXlScreen && <Spline scene="https://prod.spline.design/UZdKMgnx5mlBAL-3/scene.splinecode" />}
        </div>
        {/* 其他内容 */}
      </motion.div>
      {/* 其他内容 */}
    </section>
  );
}

2. 给容器设置固定宽高 #

即使容器初始隐藏，也为其设置明确的宽高值，让WebGL初始化时能获取有效尺寸：

<div className="hidden xl:block absolute -top-16 -right-20 scale-75 w-[800px] h-[600px]">
  <Spline scene="https://prod.spline.design/UZdKMgnx5mlBAL-3/scene.splinecode" />
</div>

注意宽高值要匹配你的Spline场景比例，避免画面拉伸变形。

3. 延迟渲染Spline组件 #

利用定时器延迟渲染Spline，确保容器已经完成显示和尺寸计算：

import Spline from "@splinetool/react-spline";
import { useState, useEffect } from 'react';

export default function LandingFeatureSection() {
  const [renderSpline, setRenderSpline] = useState(false);
  
  useEffect(() => {
    // 300ms延迟，确保容器已完成显示
    const timer = setTimeout(() => setRenderSpline(true), 300);
    return () => clearTimeout(timer);
  }, []);
  
  return (
    <section className="container flex flex-col my-20">
      {/* 其他内容 */}
      <motion.div
        initial="hide"
        whileInView="show"
        viewport={{ once: true }}
        variants={fadeRightVariant(0.5, 0.5)}
        className="flex flex-col items-center md:items-start relative w-full lg:px-4 xl:px-16 pb-20 lg:pb-0"
      >
        <div className="hidden xl:block absolute -top-16 -right-20 scale-75">
          {renderSpline && <Spline scene="https://prod.spline.design/UZdKMgnx5mlBAL-3/scene.splinecode" />}
        </div>
        {/* 其他内容 */}
      </motion.div>
      {/* 其他内容 */}
    </section>
  );
}

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