Flutter Web HTTP 통신 디버깅 설정하기

Flutter Web에서 API 통신을 하다 보면 브라우저 보안 정책 때문에 요청이 막히는 경우가 있다.
대표적으로 다음과 같은 상황이다.

발생 가능한 상황
- Flutter Web에서 HTTP API 요청이 막힘
- CORS 에러가 발생함
- 로컬 서버와 통신이 되지 않음
- Android 앱에서는 되는데 Web에서는 API 요청이 실패함

Web은 브라우저 위에서 실행되기 때문에 Android 앱보다 보안 정책의 영향을 더 많이 받는다.

특히 브라우저는 기본적으로 HTTPS 사용을 권장하고, 다른 출처의 API 요청을 제한할 수 있다.

Flutter Android
- 앱에서 직접 네트워크 요청

Flutter Web
- Chrome 브라우저 위에서 실행
- 브라우저 보안 정책 적용
- CORS, HTTPS 정책 영향을 받음

그래서 Flutter Web에서 디버깅 목적으로 브라우저 보안 옵션을 임시로 비활성화해야 하는 경우가 있다.

단, 이 방법은 개발 중 디버깅 용도로만 사용하는 것이 좋다.

주의
- 실제 배포용 설정이 아님
- 개발 / 디버깅 목적으로만 사용
- 근본적인 해결은 서버에서 CORS와 HTTPS 설정을 올바르게 하는 것

---

1. flutter_tools.stamp 제거하기

먼저 Flutter SDK 내부에 있는 flutter_tools.stamp 파일을 삭제한다.

이 파일은 Flutter Tool 관련 캐시 파일이다.

chrome.dart 같은 Flutter Tool 내부 파일을 수정한 뒤에도 기존 캐시가 남아 있으면 변경 내용이 바로 반영되지 않을 수 있다.

그래서 수정 전에 flutter_tools.stamp를 삭제한다.

flutter_tools.stamp를 삭제하는 이유
- Flutter Tool 캐시를 초기화하기 위해
- chrome.dart 수정 내용을 다시 반영하기 위해
- 기존 빌드 도구 캐시가 남아 있는 문제를 줄이기 위해

흐름은 다음과 같다.

flutter_tools.stamp 삭제
   |
   v
Flutter Tool 캐시 초기화
   |
   v
chrome.dart 수정 내용 반영 가능

보통 Flutter SDK 폴더 안에서 다음 경로를 확인한다.

flutter/packages/flutter_tools/stamp/flutter_tools.stamp

해당 파일을 삭제한 뒤 다음 단계로 넘어간다.

---

2. chrome.dart 파일 수정하기

Flutter Web은 Chrome을 실행할 때 내부적으로 chrome.dart 파일의 설정을 사용한다.

Flutter Web에서 디버깅 목적으로 브라우저 보안 정책을 비활성화하려면 이 파일에 Chrome 실행 옵션을 추가한다.

수정할 파일은 보통 Flutter SDK 내부에 있다.

flutter/packages/flutter_tools/lib/src/web/chrome.dart

이 파일에서 Chrome 실행 옵션이 들어가는 부분을 찾는다.

그리고 다음 옵션을 추가한다.

'--disable-web-security',

예시는 다음과 같다.

// '--disable-extensions',
'--disable-web-security',

이 옵션의 의미는 다음과 같다.

--disable-web-security
- Chrome의 일부 웹 보안 정책을 비활성화
- Flutter Web 디버깅 중 CORS 문제 확인에 사용 가능
- 로컬 개발 환경에서만 임시 사용 권장

---

3. 왜 이 설정이 필요한가?

Flutter Web은 Chrome 브라우저에서 실행된다.

그래서 API 요청을 보낼 때 브라우저의 보안 정책을 따른다.

Flutter Web 앱
   |
   v
Chrome 브라우저에서 실행
   |
   v
브라우저 보안 정책 적용
   |
   v
HTTP / CORS 요청이 막힐 수 있음

예를 들어 다음 상황에서 문제가 생길 수 있다.

예시
- Flutter Web 주소: http://localhost:12345
- API 서버 주소: http://localhost:8080

둘 다 localhost라 하더라도 포트가 다르면 브라우저 입장에서는 다른 출처로 판단할 수 있다.

이때 서버에서 CORS 설정이 제대로 되어 있지 않으면 요청이 차단될 수 있다.

API 요청
   |
   v
브라우저가 보안 정책 확인
   |
   v
CORS 허용 안 됨
   |
   v
요청 차단

디버깅 중에는 --disable-web-security 옵션을 사용해서 브라우저 보안 정책으로 인한 문제인지 확인할 수 있다.

---

4. 전체 적용 순서

정리하면 적용 순서는 다음과 같다.

1. Flutter SDK 폴더로 이동
2. flutter_tools.stamp 파일 삭제
3. chrome.dart 파일 열기
4. Chrome 실행 옵션에 '--disable-web-security' 추가
5. Flutter Web 다시 실행

흐름으로 보면 다음과 같다.

flutter_tools.stamp 삭제
   |
   v
chrome.dart 수정
   |
   v
--disable-web-security 옵션 추가
   |
   v
Flutter Web 다시 실행
   |
   v
HTTP / CORS 디버깅 확인

---

5. 적용 후 다시 실행하기

파일을 수정한 뒤 Flutter Web을 다시 실행한다.

flutter run -d chrome

또는 사용 가능한 기기를 먼저 확인할 수 있다.

flutter devices

Chrome으로 실행할 수 있다면 다음처럼 실행한다.

flutter run -d chrome

---

6. 주의할 점

이 방법은 보안 정책을 우회하는 방식이다.

따라서 실제 서비스나 배포 환경에서 사용하는 해결책은 아니다.

주의할 점
- 개발용으로만 사용
- 실제 배포 환경에서는 사용하면 안 됨
- Flutter SDK 내부 파일을 수정하는 방식이므로 Flutter 업데이트 시 초기화될 수 있음
- 팀 프로젝트에서는 다른 개발자 환경에 자동 적용되지 않음
- 근본 해결은 서버 CORS 설정과 HTTPS 적용

실제 서비스에서는 서버에서 CORS를 허용해야 한다.

예를 들어 서버가 다음 Origin을 허용해야 한다.

허용해야 할 수 있는 Origin 예시
- http://localhost:포트번호
- https://배포도메인

---

7. 정리

Flutter Web에서 HTTP 통신 또는 CORS 문제를 디버깅할 때 Chrome 보안 옵션을 임시로 비활성화할 수 있다.

핵심 순서는 다음과 같다.

1. flutter_tools.stamp 삭제
2. chrome.dart 수정
3. '--disable-web-security' 옵션 추가
4. flutter run -d chrome 실행

수정할 옵션은 다음과 같다.

// '--disable-extensions',
'--disable-web-security',

각 설정의 의미는 다음과 같다.

flutter_tools.stamp 삭제
- Flutter Tool 캐시 초기화

chrome.dart 수정
- Chrome 실행 옵션 변경

--disable-web-security
- 개발 중 브라우저 보안 정책을 임시로 비활성화

마지막으로 가장 중요한 점은 다음과 같다.

이 방법은 디버깅용 임시 해결책이다.
실제 해결은 서버에서 CORS 설정을 올바르게 하고 HTTPS를 적용하는 것이다.