·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 編碼能力。