·Any3D Team
OffscreenCanvas 不可用？按平台与环境排查
troubleshootingbrowser-compatibilityoffscreencanvas
你看到的症状
Any3D 提示「当前浏览器不支持 OffscreenCanvas」。这是 Worker 路径三件套之一；缺失后纹理压缩等需在 Worker 内使用 WebGL2 编码的流程无法完整运行。
OffscreenCanvas 允许在 Web Worker 中创建画布并获取 WebGL 上下文，在后台完成 GPU 操作而不阻塞页面。
常见原因
| 原因 | 典型场景 |
|---|---|
| 浏览器/WebView 过旧 | Chrome < 69、Safari < 16.4、旧 Android WebView |
| 硬件加速关闭 | Windows/macOS 节能或策略关闭 GPU |
| 企业策略 | GPO 禁用 GPU、MDM 限制图形能力 |
| 内嵌 WebView | 微信、企业 App、Electron 旧壳 |
| 网络层 | 少见；多为脚本加载失败而非 API 本身 |
按平台排查
Windows
- Chrome / Edge：设置 → 系统 → 开启「使用硬件加速」→ 完全退出并重启浏览器。
- 显卡驱动：笔记本双显卡时，确保浏览器使用独立显卡（NVIDIA 控制面板 / AMD Software）。
- 组策略：「禁用硬件加速」类策略会导致 OffscreenCanvas WebGL 上下文创建失败。
- 远程桌面（RDP）：部分 RDP 会话 GPU 能力受限，本地登录对比测试。
macOS
- Safari 16.4+ 或 Chrome 最新版。
- 系统设置 → 电池 → 低电量模式可能降低 GPU 调度；插电重试。
- 屏幕使用时间 一般不直接禁用 OffscreenCanvas，但 MDM 限制图形 API 时需联系 IT。
Linux
- 确认 Mesa/专有驱动正常；Wayland 与 X11 下均用最新 Chrome 测试。
- 无头服务器远程浏览器需虚拟 GPU（少见个人场景）。
iOS / iPadOS
- Safari 随系统更新（iOS 16.4+ 起 OffscreenCanvas 支持较完整）。
- App 内 WebView 可能落后系统 Safari——在 Safari 中打开链接。
- 学校 iPad 监管模式可能锁定旧系统，需管理员更新。
Android
- 更新 Chrome 与 Android System WebView。
- 国产浏览器兼容核不支持 → 切极速核或用 Chrome。
- 低端机 GPU 驱动过旧：尝试关闭「省电模式」后重试。
网络、VPN 与企业环境
OffscreenCanvas 是本地 API，通常不受 VPN 直接影响。但若 VPN 导致浏览器降级为「安全模式」或加载了企业扩展注入脚本，可能间接失败：
- 断开 VPN 对比；
- 检查企业浏览器是否强制「软件渲染」；
- iframe 内嵌时确认外层未阻止 Worker 内的 WebGL。
家长控制与监管设备
- Family Link / 屏幕使用时间：极少直接禁用 OffscreenCanvas；更常见是禁止安装浏览器更新导致 API 过旧——允许系统自动更新。
- 考场/图书馆模式：可能使用定制浏览器，建议换个人设备。
分步修复（通用）
- 更新浏览器到上表最低版本以上。
- 开启硬件加速并重启浏览器。
- 系统浏览器打开，勿用 App 内 WebView。
- 若同时有 WebGL2 报错，先处理 WebGL2 修复指南。
快速自测
typeof OffscreenCanvas !== "undefined"
返回 false 表示当前环境不支持该 API。
小结
OffscreenCanvas 缺失多见于 旧浏览器/WebView、硬件加速关闭、Windows 远程或企业 GPU 策略。按平台开启 GPU 加速、更新 WebView、改用系统浏览器，通常可恢复 Worker 内 GPU 编码能力。