31 lines
2.4 KiB
Markdown
31 lines
2.4 KiB
Markdown
# 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。通过临时实例承接流量,等待旧实例请求结束后切换主实例;上一版构建保留用于回滚。
|