Flutter 웹 빌드 시 한글 폰트 깨짐 해결

문제 상황

Flutter 1.17 stable로 웹 프로젝트를 빌드해 배포했는데, 한글이 제대로 렌더링되지 않고 네모 박스로 표시되는 문제가 발생했다. 로컬 개발 환경에서는 문제가 없었는데 프로덕션 빌드에서만 발생했다.

원인 분석

Flutter 웹은 기본적으로 CanvasKit 렌더러를 사용하는데, 이 경우 시스템 폰트를 자동으로 불러오지 못한다. 개발 모드에서는 HTML 렌더러를 사용해 시스템 폰트가 적용되지만, 프로덕션 빌드는 CanvasKit이 기본이라 커스텀 폰트를 명시적으로 포함해야 한다.

해결 방법

1. 폰트 파일 추가

pubspec.yaml에 한글 폰트를 추가했다.

flutter:
  fonts:
    - family: NotoSansKR
      fonts:
        - asset: fonts/NotoSansKR-Regular.otf
        - asset: fonts/NotoSansKR-Bold.otf
          weight: 700

2. 전역 테마 설정

MaterialApp(
  theme: ThemeData(
    fontFamily: 'NotoSansKR',
  ),
  // ...
)

3. 빌드 옵션 확인

필요시 HTML 렌더러로 빌드할 수도 있다.

flutter build web --web-renderer html

다만 CanvasKit이 성능과 일관성 면에서 더 낫기 때문에 폰트를 포함하는 방식을 선택했다.

결과

폰트 파일 크기가 약 2MB 정도 증가했지만, 모든 환경에서 한글이 정상적으로 표시되었다. 웹 폰트 로딩 최적화는 추후 과제로 남겨뒀다.