Next.js项目中react-unity-webgl加载Unity游戏失败无报错求助

环境版本信息 #

• Unity: 2021.3.16f1（游戏导出版本）
• 项目依赖版本：
  • next: ^13.1.6
  • react: ^18.2.0
  • react-unity-webgl: ^9.4.0

问题描述 #

在Next.js构建环境中加载Unity导出的WebGL游戏，页面无法显示游戏内容，浏览器控制台无任何报错信息，无法定位失败原因。

使用代码 #

import { Unity, useUnityContext } from 'react-unity-webgl';

export default function GamesPage() {
  const { unityProvider } = useUnityContext({
    loaderUrl: '/testBuildThree/Build/testBuildThree.loader.js',
    dataUrl: '/testBuildThree/Build/testBuildThree.data',
    frameworkUrl: '/testBuildThree/Build/testBuildThree.framework.js',
    codeUrl: '/testBuildThree/Build/testBuildThree.wasm',
  });

  return (
    <div>
      <p>Game</p>
      <Unity
        unityProvider={unityProvider}
        style={{ width: 800, height: 600, border: 'solid black 1px' }}
      />
    </div>
  );
}

静态文件与页面效果截图 #

• 静态文件夹中构建文件结构：
• 页面加载效果：

排查方向与解决方案 #

1. 验证静态资源路径 #

• 确认Unity构建文件已放置在Next.js的public目录下，路径需与代码配置完全匹配：public/testBuildThree/Build/下必须包含loader.js、data、framework.js、wasm四个文件。
• 直接访问资源URL（如http://localhost:3000/testBuildThree/Build/testBuildThree.loader.js），若返回404则说明路径配置错误，需调整文件位置或代码中的路径参数。

2. 适配Next.js 13架构 #

• 若使用Next.js 13的App Router（默认新架构），需在页面文件顶部添加客户端组件标识：

  "use client";
  

• 可尝试启用动态渲染避免静态构建时的资源加载问题：

  export const dynamic = "force-dynamic";
  

• 也可临时将页面移至pages目录（使用Pages Router）测试，确认是否为架构兼容性问题。

3. 检查Unity导出配置 #

• 重新导出Unity项目，确保选择WebGL平台，导出过程无报错，所有文件完整输出。
• 检查Unity Player设置中的Resolution and Presentation，使用默认的WebGL模板，避免自定义模板导致加载逻辑冲突。

4. 添加错误与状态监听 #

• 修改代码添加加载状态和错误捕获，定位静默失败原因：

  import { Unity, useUnityContext } from 'react-unity-webgl';
  
  export default function GamesPage() {
    const { unityProvider, isLoaded, loadingProgression, error } = useUnityContext({
      loaderUrl: '/testBuildThree/Build/testBuildThree.loader.js',
      dataUrl: '/testBuildThree/Build/testBuildThree.data',
      frameworkUrl: '/testBuildThree/Build/testBuildThree.framework.js',
      codeUrl: '/testBuildThree/Build/testBuildThree.wasm',
    });
  
    if (error) {
      return <p>游戏加载失败: {error.message}</p>;
    }
  
    if (!isLoaded) {
      return <p>加载进度: {Math.round(loadingProgression * 100)}%</p>;
    }
  
    return (
      <div>
        <p>Game</p>
        <Unity
          unityProvider={unityProvider}
          style={{ width: 800, height: 600, border: 'solid black 1px' }}
        />
      </div>
    );
  }
  

5. 浏览器环境检查 #

• 清除浏览器缓存并强制刷新页面（Ctrl+Shift+R），避免缓存的旧资源干扰加载。
• 确认浏览器已启用WebAssembly：Chrome可通过chrome://flags/#enable-webassembly查看状态，确保选项为启用。

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