·Any3D Team
WebGL2 不可用？3D 预览按平台排查
troubleshootingbrowser-compatibilitywebgl2
你看到的症状
预览区提示「3D 预览不可用」，或页面空白、无模型显示。Any3D 的在线预览依赖 WebGL2 在 GPU 上渲染 3D 场景；WebGL2 不可用时预览无法启动。
常见原因
| 原因 | 典型场景 |
|---|---|
| 硬件加速关闭 | 浏览器或系统设置禁用 GPU |
| 显卡驱动过旧/异常 | Windows 笔记本双显卡、Linux 开源驱动 |
| 浏览器黑名单 | 极旧 GPU 被浏览器列入软件渲染列表 |
| 远程桌面 / 虚拟机 | RDP、VM 无 GPU 透传 |
| 企业策略 | GPO 禁用硬件加速、VDI 无 3D 加速 |
| WebView / 旧内核 | 微信、钉钉、旧 App |
| 扩展干扰 | 强制 Canvas 指纹防护类插件 |
按平台排查
Windows
-
开启硬件加速
Chrome/Edge：设置 → 系统 →「使用硬件加速（如可用）」→ 重启浏览器。 -
更新显卡驱动
NVIDIA / AMD / Intel 官网或 Windows Update 安装最新驱动。笔记本在显卡控制面板中将浏览器设为「高性能」。 -
组策略 / 注册表（企业）
IT 可能通过策略禁用 GPU 合成。个人用户可检查chrome://gpu是否大量「Software only」。 -
远程桌面
RDP 到办公机时 WebGL 常不可用——本地 PC 浏览器打开 Any3D，或使用支持 GPU 的远程方案。 -
家长控制
Windows 家庭安全子账户一般不禁 WebGL；若使用第三方「儿童浏览器」，换 Chrome/Edge 测试。
macOS
- Safari / Chrome 最新版；系统设置 → 显示器 → 刷新率/分辨率正常即可。
- 低电量模式 下 GPU 降频，极端情况影响 WebGL——插电重试。
- 屏幕使用时间 不直接禁 WebGL；MDM 限制图形时需联系 IT。
Linux
- 专有驱动（NVIDIA）或较新 Mesa；
chrome://gpu查看 GL 状态。 - Wayland 与 X11 若一侧失败可切换会话对比。
iOS / iPadOS
- Safari 对 WebGL2 支持较好；保持系统更新。
- 低电量模式 可能限制性能，预览卡顿或失败——充电后重试。
- App 内 WebView → Safari 打开。
- 学校监管 iPad 若禁止「相机/文件」不影响 WebGL，但禁止系统更新会导致内核过旧。
Android
- 更新 Chrome；开启 开发者选项 → 强制 GPU 渲染（部分旧机有效，新系统可能已默认）。
- 国产浏览器兼容核常无 WebGL2 → 用 Chrome。
- 省电模式 限制 GPU——关闭后重试。
网络、VPN 与企业内网
WebGL2 为本地 GPU API，通常不受 VPN 直接影响。但以下情况需留意：
| 场景 | 说明 |
|---|---|
| 企业 VDI（Citrix/VMware） | 未启用 GPU 透传时 WebGL 不可用，需 IT 开启 vGPU 或本地浏览器 |
| VPN 强制安装浏览器扩展 | 扩展可能干扰 WebGL 上下文 |
| 内网仅允许 IE/旧 Edge | 无 WebGL2，必须换现代 Chromium 浏览器 |
家长控制与公共环境
- 图书馆/学校 PC：可能使用锁定版浏览器或无独显——换个人笔记本验证。
- Family Link 限制 Chrome 版本：允许 Play 商店更新 Chrome。
分步修复（通用）
- 打开
chrome://gpu（Chrome/Edge）或about:support→ 图形，查看 WebGL2 是否 Hardware accelerated。 - 开启硬件加速，更新驱动，重启浏览器与系统。
- 无痕窗口排除扩展。
- 换浏览器 / 换设备交叉验证。
快速自测
(() => {
const c = document.createElement("canvas");
return c.getContext("webgl2") !== null;
})()
返回 false 表示无法创建 WebGL2 上下文。
也可访问 WebGL Report（需可访问外网）查看详细能力。
与 OffscreenCanvas 的关系
纹理压缩 Worker 路径也需要 OffscreenCanvas + WebGL2。若仅底部黄色 Worker 警告而预览正常，优先查 OffscreenCanvas 指南；若预览本身失败，以本文为主。
小结
WebGL2 不可用核心是 GPU/驱动/硬件加速 问题，企业 VDI、远程桌面、旧 WebView 也很常见。按平台开启加速、更新驱动、本地浏览器访问，多数可恢复 3D 预览。