·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 | WeChat, 기업 앱, 구형 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 지원이 상대적으로 완전합니다).
- 앱 내 WebView는 시스템 Safari보다 뒤처질 수 있으므로, Safari에서 직접 링크를 열어 테스트하세요.
- 학교 iPad 감독 모드에서는 구형 시스템으로 잠겨 있을 수 있어 관리자가 업데이트해야 합니다.
Android
- Chrome과 Android System WebView를 최신 버전으로 업데이트합니다.
- 중국 브라우저 호환 모드는 지원하지 않으므로, 고속 모드로 전환하거나 Chrome을 사용합니다.
- 저사양 기기의 GPU 드라이버가 너무 오래된 경우: 「절전 모드」를 비활성화한 후 다시 시도해 보세요.
네트워크, VPN 및 기업 환경
OffscreenCanvas는 로컬 API이므로, 보통 VPN에 의해 직접 영향을 받지 않습니다. 그러나 VPN이 브라우저를 「안전 모드」로 다운그레이드하거나 기업 확장 프로그램 주입 스크립트를 로드하게 되면 간접적으로 실패할 수 있습니다:
- VPN 연결을 끊고 비교 테스트합니다.
- 기업 브라우저가 「소프트웨어 렌더링」을 강제하는지 확인합니다.
- iframe 내장 시, 바깥 층이 Worker 내 WebGL을 차단하지 않는지 확인합니다.
부모 제어 및 감독 기기
- Family Link / 화면 사용 시간: OffscreenCanvas를 직접 비활성화하는 경우는 매우 드뭅니다. 더 흔한 것은 브라우저 업데이트 설치를 금지하여 API가 오래되게 하는 것입니다—시스템 자동 업데이트를 허용하세요.
- 시험장/도서관 모드: 맞춤형 브라우저를 사용할 수 있으므로, 개인 기기를 사용하는 것이 좋습니다.
단계별 해결 방법 (일반)
- 브라우저를 위 표의 최소 버전 이상으로 업데이트합니다.
- 하드웨어 가속을 활성화하고 브라우저를 다시 시작합니다.
- 시스템 브라우저에서 열거나, 앱 내 WebView를 사용하지 마세요.
- 동시에 WebGL2 오류가 발생하면, 먼저 WebGL2 해결 가이드를 참조하세요.
빠른 자체 테스트
typeof OffscreenCanvas !== "undefined"
결과가 false이면 현재 환경에서 해당 API를 지원하지 않는 것입니다.
요약
OffscreenCanvas 부족은 오래된 브라우저/WebView, 하드웨어 가속 비활성화, Windows 원격 데스크톱 또는 기업 GPU 정책에서 흔히 발생합니다. 플랫폼별로 GPU 가속을 활성화하고, WebView를 업데이트하며, 시스템 브라우저로 전환하면 일반적으로 Worker 내 GPU 인코딩 기능을 복구할 수 있습니다.