发布Unity默认AR项目至React Unity WebGL时出现序列化布局错误

开发环境 #

• Macbook M1 Pro（搭载Apple Silicon芯片）
• Unity 2021.3.10f1（兼容Apple Silicon芯片）
• Chrome浏览器测试

当前操作进度 #

1. 使用AR模板创建新Unity项目
2. 项目层级结构如图所示
   
3. 构建设置如图所示
   
4. 构建后生成4个文件：build.data, build.framework.js, build.loader.js, build.wasm
5. 通过create-react-app命令创建TypeScript React项目：npx create-react-app ar_tutorial_4 --template typescript
6. 将上述4个构建文件放入React项目的build目录，如图所示
   
7. 修改index.html文件如下

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>React Unity webGL</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
  </body>
</html>

8. 修改App.tsx和index.tsx文件如下

// App.tsx
import { useRef } from "react";
import { Unity, useUnityContext } from "react-unity-webgl";

function UnityTest() {
  const {
    unityProvider,
    isLoaded,
    loadingProgression,
  } = useUnityContext({
    codeUrl: '/build/build.wasm',
    dataUrl: '/build/build.data',
    frameworkUrl: '/build/build.framework.js',
    loaderUrl: '/build/build.loader.js',
    webglContextAttributes: {
      preserveDrawingBuffer: true,
    },
  });

  const loadingPercentage = Math.round(loadingProgression * 100);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  return (
    <div className="container">
      {isLoaded === false && (
        <div className="loading-overlay">
          <p>Loading... ({loadingPercentage}%)</p>
        </div>
      )}
      <Unity
        className="unity"
        unityProvider={unityProvider}
        style={{ border: "1px solid red", height: 400, width: 500 }}
        devicePixelRatio={window.devicePixelRatio}
        ref={canvasRef}
      />
    </div>
  );
}

export { UnityTest };

// index.tsx
import React, { createElement } from 'react';
import ReactDOM from 'react-dom/client';
import { UnityTest } from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(createElement(UnityTest));

问题现象 #

加载完成后Unity容器无法正常运行，控制台报错：

build.framework.js:1771 A scripted object (script unknown or not yet loaded) has a different serialization layout when loading. (Read 52 bytes but expected 76 bytes)
Did you #ifdef UNITY_EDITOR a section of your serialized properties in any of your scripts?

求助问题 #

请问该如何解决此序列化布局不匹配错误？

解决方案 #

这个错误本质是Unity序列化数据与运行时脚本结构不匹配，按以下步骤排查修复：

1. 检查脚本中的#ifdef UNITY_EDITOR序列化代码
   报错提示明确指向这类情况，若脚本中用#ifdef UNITY_EDITOR包裹了序列化变量（如public或[SerializeField]标记的字段），WebGL构建时这些代码会被剔除，导致序列化数据结构和运行时脚本不一致。打开所有自定义脚本，移除这类条件编译的序列化属性，或确保编译前后序列化字段的数量、类型完全一致。

2. 清理并重新构建Unity项目
   关闭Unity，删除项目目录下的Library、Temp、Obj文件夹，清空WebGL构建输出目录；重新打开Unity，等待资源重新导入后，重新执行WebGL构建，确保构建过程无警告或错误。

3. 验证资源与场景的序列化一致性
   检查场景中所有挂载脚本的对象，确认脚本未被误删除或替换，避免出现"script unknown"的情况；若使用AssetBundle，确保Bundle与当前构建的脚本版本完全匹配，禁止混用不同版本的Bundle。

4. 检查Unity版本与构建设置
   确认Unity 2021.3.10f1为稳定版本，无已知WebGL序列化bug；检查WebGL构建设置：确保"Scripting Backend"设为IL2CPP（WebGL推荐），"Optimization Level"选择合理级别，不要开启会破坏序列化的激进优化。

5. 验证React项目中构建文件的完整性
   确保从Unity导出的4个构建文件完整复制到React项目的build目录，无文件损坏或遗漏；清除浏览器缓存，或用无痕模式测试，避免加载旧缓存文件。

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