Flutter Web 3.50 이상에서 --wasm release를 배포한다면, 빌드 성공보다 브라우저가 받은 응답 헤더를 먼저 확인해야 한다. 서버가 Cross-Origin-Opener-Policy: same-origin과 Cross-Origin-Embedder-Policy: credentialless(또는 require-corp)를 보내지 않으면 멀티스레드 WASM 경로를 사용할 수 없다. 헤더를 설정할 수 없는 정적 호스팅이라면 WASM을 억지로 고정하기보다 JavaScript 빌드 fallback을 선택하는 편이 낫다.
오류가 빌드 단계에서 보이지 않는 이유
flutter build web --wasm은 산출물을 정상적으로 만든다. 문제는 배포 뒤 브라우저가 실행 환경을 판별할 때 나타난다. 헤더가 없으면 SharedArrayBuffer 기반 멀티스레드 실행이 막히거나, 브라우저가 요구하는 Wasm 기능을 지원하지 않아 fallback이 선택된다. 따라서 “빌드 성공”과 “WASM 경로로 실행”은 별도 검사다.
| 확인 대상 | Flutter 공식 기준 | 운영 판단 |
|---|---|---|
| Flutter SDK | --web-content-hash는 3.50 이상 |
구버전이면 해시 옵션과 WASM 조건을 분리 확인 |
| 브라우저 | Chrome·Edge·Opera·Brave는 137 이상에서 주요 WASM 경로 지원 | 오래된 사내 브라우저는 JS fallback 대상 |
| 응답 헤더 | COOP same-origin + COEP credentialless 또는 require-corp |
멀티스레드 WASM을 쓸 때 필수 |
| 호스팅 | 사용자 정의 보안 헤더 설정 가능 여부 | GitHub Pages처럼 제어가 제한되면 기대 경로를 낮춤 |
release 빌드와 서버 헤더를 함께 맞춘다
WASM 파일만 생성하는 명령은 아래와 같다. source map은 공개 서버에 올리지 않고 오류 추적 서비스로 보내는 편이 안전하다.
flutter build web --wasm --source-maps --web-content-hash
Firebase Hosting처럼 응답 헤더를 지정할 수 있는 환경이라면 firebase.json의 hosting 설정에 아래 정책을 추가한다. 실제 프로젝트의 다른 API·이미지 도메인이 credentialless 정책과 충돌하는지는 별도로 확인해야 한다.
{
"hosting": {
"public": "build/web",
"headers": [
{
"source": "**",
"headers": [
{ "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
{ "key": "Cross-Origin-Embedder-Policy", "value": "credentialless" }
]
}
]
}
}
이 설정은 모든 하위 경로에 적용되므로 외부 iframe, 결제 위젯, 다른 출처의 리소스가 있는 앱은 바로 복사하면 안 된다. credentialless 적용 뒤 이미지·스크립트가 사라지면 해당 리소스 응답의 CORS 또는 CORP 조건을 조정하거나 멀티스레드 경로를 포기해야 한다. COEP를 require-corp로 바꾸는 것도 자동 해결책은 아니다.
브라우저와 배포 결과를 재현하는 체크리스트
헤더는 개발 서버가 아니라 실제 release URL에서 확인한다.
curl -sI https://example.com/ | rg -i 'cross-origin|content-type|cache-control'
flutter --version이 3.50 이상이고--wasm산출물이 생성됐다.- 실제 URL의 응답에 COOP와 COEP가 모두 있다.
- Chrome 137 이상과 지원 대상 브라우저에서 로그인·라우팅·파일 업로드를 실행했다.
- 오래된 브라우저에서 JS fallback 또는 지원 불가 안내가 의도대로 보인다.
- 외부 iframe과 CDN 리소스가 헤더 적용 뒤에도 로드된다.
- 소스 맵은 공개
build/web배포 대상에서 제외했다.
정적 호스팅이 보안 헤더를 바꿀 수 없거나 외부 리소스가 많은 서비스라면 WASM 멀티스레드가 필수인지부터 판단해야 한다. 단순히 다운로드 크기나 벤치마크 때문에 바꾸는 앱이라면 현재의 JavaScript 빌드를 유지하는 것이 무료이고 복구 비용도 작다. 반대로 WASM을 선택했다면 브라우저 버전, 응답 헤더, 외부 리소스 정책을 하나의 출시 승인 조건으로 묶어야 한다.
참고 기준은 Flutter WebAssembly 공식 문서와 Flutter Web 빌드·배포 문서다. 두 문서는 2026년 10월 31일 확인했으며, 브라우저 지원 범위와 서버 헤더 요구 조건은 배포 환경에 따라 달라질 수 있다.