Flutter Web 이미지가 안 보일 때: CORS·CanvasKit·배포 점검
Flutter Web에서 외부 이미지가 모바일에서는 보이지만 웹에서 실패하는 이유를 브라우저의 Same-Origin Policy와 CORS 관점에서 설명하고, 서버 응답과 Flutter 코드를 점검하는 방법을 정리한다.
모바일 앱은 외부 URL의 이미지를 정상적으로 읽는데 Flutter Web에서는 CORS 오류가 발생할 수 있다. Flutter 문제가 아니라 브라우저 보안 모델의 차이에서 시작한다.
sequenceDiagram
participant App as Flutter Web
participant Browser as Browser
participant CDN as Image Server
App->>Browser: 외부 이미지 요청
Browser->>CDN: Origin 헤더와 요청
CDN-->>Browser: Access-Control-Allow-Origin
Browser->>Browser: Origin 허용 여부 검사
Browser-->>App: 이미지 노출 또는 차단
Same-Origin과 CORS
프로토콜, 호스트, 포트 중 하나라도 다르면 다른 Origin이다.
https://app.example.com
https://cdn.example.com
CDN이나 이미지 서버가 Flutter Web 도메인을 허용하도록 응답해야 한다.
Access-Control-Allow-Origin: https://app.example.com
공개 리소스라면 정책에 따라 *를 사용할 수 있지만 인증 쿠키와 함께 사용할 때는 제약이 있다.
Flutter 코드
Image.network(
imageUrl,
fit: BoxFit.cover,
errorBuilder: (context, error, stackTrace) {
return const ColoredBox(
color: Color(0xFFEAEAEA),
child: Center(child: Icon(Icons.broken_image_outlined)),
);
},
)
errorBuilder는 사용자 경험을 보완하지만 CORS를 해결하지는 않는다. 근본 해결은 이미지 서버의 응답 헤더다.
점검 순서
- 브라우저 개발자 도구의 Network와 Console을 확인한다.
- 이미지 URL을 새 탭에서 여는 것과 앱에서 사용하는 것을 구분한다.
- 응답에
Access-Control-Allow-Origin이 있는지 확인한다. - CDN 캐시에 이전 헤더가 남아 있지 않은지 확인한다.
- Redirect된 최종 URL의 헤더도 확인한다.
- 서명 URL의 만료 시간과 Query String을 확인한다.
curl -I \
-H 'Origin: https://app.example.com' \
'https://cdn.example.com/image.png'
로컬에서 Release 빌드 확인
flutter build web --release
dart pub global activate dhttpd
dhttpd --path build/web --port 8000
file://로 직접 index.html을 열면 실제 서버 환경과 다르게 동작할 수 있으므로 HTTP 서버로 확인한다.
Source Map
flutter build web --release --source-maps
Source Map은 압축된 JavaScript 오류를 Dart 소스 위치로 추적하는 데 사용한다. 운영 서버에 무조건 공개하기보다 오류 모니터링 서비스에 별도로 업로드하는 정책을 권장한다.
관련 문서
다른 게시글
현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어
기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.
Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분
Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.
Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정
Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.