[Model3D] 3D model preview doesn’t work when the app is embedded using web components

快速结论：该问题发生在通过 Web Components 内嵌 Gradio 应用时，Model3D 的 3D 模型预览无法正常显示，但直接访问原始 Space 链接时正常工作。优先排查 Web Components 加载方式下的 3D 渲染兼容性，该问题已由 babylon.js 版本更新修复。

问题场景

用户在 Gradio 应用中使用 Web Components 嵌入方式展示 Model3D 组件时（例如 https://www.gradio.app/docs/model3d 中嵌入的 Space），3D 模型预览显示为空白或无法渲染。直接访问原始 Hugging Face Space（https://huggingface.co/spaces/gradio/model3D）时功能正常。

报错原文

No specific error log provided. Symptom: 3D model preview area is blank when embedded via web components.

原因分析

该问题与 Web Components 嵌入方式下的 3D 渲染环境有关。原始 Issue 评论确认问题仅出现在 Web Components 嵌入时（iframe 方式正常）。最终修复是通过更新 babylon.js 库版本解决的，因此可能原因是旧版本 babylon.js 在 Web Components 的 Shadow DOM 作用域下存在渲染兼容性问题。

环境排查

确认 Gradio 版本（建议升级到 4.x 最新版）
确认 babylon.js 版本（修复涉及版本更新）
确认 Web Components 的嵌入方式（是否使用了 <gradio-app> 标签）
检查浏览器控制台是否有 JavaScript/CSS 相关的错误（如跨域或作用域异常）

解决步骤

升级 Gradio 到包含 babylon.js 修复的最新版本（例如 4.26.0 或更高，具体版本需参考官方发布日志）。
如果无法立即升级，可先通过 iframe 方式嵌入 Space 作为临时替代方案（经测试 iframe 方式工作正常）。
清理浏览器缓存并重新加载嵌入页面，确保所有资源使用最新版本。
可优先尝试：在嵌入页面中显式加载最新 babylon.js 脚本，检查是否解决兼容性问题。

验证方法

在嵌入页面中观察 Model3D 组件是否能正常渲染出 3D 模型。如果之前为空白，修复后应显示为可交互的 3D 预览区域。对照原始 Space 直接访问的表现进行确认。

参考来源

gradio-app/gradio #7485

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[Model3D] 3D model preview doesn’t work when the app is embedded using web components