COOP/COEP로 Wasm 스레드(SharedArrayBuffer) 활성화하기

웹 게임(또는 엔진 익스포트)이 WebAssembly 스레드를 사용한다면, 보통 SharedArrayBuffer에 의존하게 됩니다. 최신 브라우저는 이를 위해 **교차 출처 격리(cross-origin isolation)**를 요구합니다.

1) 빠른 확인: 격리 상태인가요?

DevTools를 열고 다음을 실행하세요.

self.crossOriginIsolated

true가 나오면 SharedArrayBuffer를 쓰기에 적합한 보안 상태입니다.

공식 참고 자료:

• https://developer.mozilla.org/docs/Web/API/Window/crossOriginIsolated

2) 필요한 두 개의 헤더

HTML(그리고 보통은 앱 전체)의 응답에 다음 헤더를 추가하세요.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

공식 참고 자료:

• https://web.dev/articles/why-coop-coep
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
• https://developer.chrome.com/blog/enabling-shared-array-buffer/

3) "그래도 안 되는" 가장 흔한 이유: 하위 리소스

COEP: require-corp를 켜면 페이지가 더 이상 교차 출처 리소스를 자유롭게 임베드할 수 없습니다.

교차 출처의 스크립트/이미지/worker/비디오 등을 불러온다면, 그 리소스가 다음 중 하나로 명시적으로 허용해야 합니다.

• CORS (Access-Control-Allow-Origin) 또는
• CORP (Cross-Origin-Resource-Policy)

공식 참고 자료:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cross-Origin_Resource_Policy

4) 복사-붙여넣기 설정

Nginx

add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;

Node / Express

app.use((req, res, next) => {
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
  next()
})

Cloudflare Pages (_headers)

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

5) 디버깅 체크리스트

• Network 패널에서 문서 응답에 이 헤더들이 있는지 확인하세요.
• self.crossOriginIsolated 값을 확인하세요.
• 차단된 요청을 찾아보세요 (DevTools에서 흔히 보이는 메시지에 "blocked … by COEP"가 포함됩니다).
• CORS/CORP를 지원하지 않는 서드파티 스크립트는 제거하거나 직접 호스팅하세요.

관련 글

• 빠르게 로드되는 웹 게임 출시하기
• 2026년 웹 게임 기술 스택
• 게임 로직을 위한 Web Workers — SharedArrayBuffer의 이점을 누리는 Worker 사용하기
• WebSocket 멀티플레이어 기초 — 교차 출처 격리가 필요한 멀티플레이어 게임
• Iframe으로 게임 임베드하기 — COOP/COEP 헤더가 iframe 임베드에 미치는 영향

외부 자료

• MDN: Cross-Origin-Opener-Policy — COOP 헤더 참고 자료
• MDN: Cross-Origin-Embedder-Policy — COEP 헤더 참고 자료
• web.dev: Making your website cross-origin isolated — 실용적인 배포 가이드