2.4 KiB
Claw 3D 预览黑屏（2026-09-15）
已复现的原因
交互查看器与基础查看器都使用 Drei 的远程环境预设。当前依赖版本会向 raw.githack.com 下载 HDR 灯光贴图，且模型与环境处于同一 Suspense 边界。即使 GLB 已返回，环境请求一直等待也会隐藏整个模型；交互查看器的等待占位原为 null，表现为黑色空白。
将外部网络请求挂起、GLB 正常返回的 Chrome WebGL 测试中，旧版两种查看器均未完成挂载，画布可见模型像素为 0。修复后两个查看器都完成挂载并渲染模型，灯光不再发起外部请求。已用此前故障排查保存的真实家具 GLB 验证两种查看器均显示正常。未取得本次反馈用户的浏览器网络记录，不能将模拟结果当作该用户的实测网络错误。
线上检查时，9 月 15 日检索到的 76 次 Claw 附件请求全部返回 HTTP 200；这不能证明用户浏览器访问外部环境资源也成功。
修改
- Claw 两种查看器使用本地 RoomEnvironment/PMREM 生成灯光反射，不再等待外部 HDR。生成失败时保留直接灯光，卸载时释放 GPU 资源。
- 其他 3D 页面的环境预设选项保留，环境与模型分别使用 Suspense，环境等待不再阻止模型显示。
- GLB 等待时显示文字提示，15 秒后提示加载较慢；明确区分失败与静态预览。
- 交互清单等待超过 15 秒后取消请求，切换到基础 3D 查看器，保留清单超时提示。
验证
node scripts/verify-claw-3d-loading.mjs 使用实际组件、Chrome WebGL 和本地合成 GLB，验证外部请求不可用、慢模型加载提示、交互清单超时及模型 HTTP 失败提示。
--source-ref=54c857d7 可复现旧查看器因外部请求挂起而空白；--model-file=<local GLB> 可检查本地真实模型，不上传文件。
15 项 tests/routes/openclaw-3d-artifacts.test.ts 测试通过；TypeScript 检查通过。浏览器测试未调用生产生成功能、未修改业务数据，真实模型文件不入库。
开发分支补充记录：
发布
生产构建通过，修复发布到 48 服务器：代码提交 73593051，构建 0wDzz4WyOuL9um6ei6V_k，目录 .next-claw-3d-loading-0915。线上登录页、新运行时及两种查看器资源均返回 200，匿名历史接口仍返回 401。通过临时实例承接流量，等待旧实例请求结束后切换主实例；上一版构建保留用于回滚。