ai-chatbot/docs/incidents/claw-3d-black-screen-2026-09-15.md

31 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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