Flutter 튜토리얼 59편: 웹 앱 개발

이번 튜토리얼에서는 Flutter로 웹 애플리케이션을 개발하는 방법을 배워보겠습니다. 웹 지원 설정부터 개발, 빌드까지의 전체 과정을 다룹니다.

학습 목표#

이번 튜토리얼을 완료하면 다음을 할 수 있습니다:

Flutter 웹 개발 환경을 설정할 수 있습니다
웹 프로젝트를 생성하고 실행할 수 있습니다
웹 렌더러¹의 종류와 특징을 이해할 수 있습니다
웹 앱을 빌드하고 배포를 준비할 수 있습니다

Chapter 1: Flutter 웹 지원 이해하기#

1.1 Flutter 웹의 특징#

Flutter는 하나의 코드베이스로 iOS, Android, 웹, 데스크톱 앱을 만들 수 있습니다.

왜 Flutter 웹인가요?
Flutter 웹을 사용하면 다음과 같은 장점이 있습니다:

코드 재사용: 모바일 앱과 동일한 코드를 웹에서도 사용할 수 있습니다

일관된 UI: 모든 플랫폼에서 동일한 사용자 경험을 제공합니다

WebAssembly² 지원: 네이티브에 가까운 성능을 제공합니다

Hot Reload 지원: 빠른 개발 사이클을 유지할 수 있습니다

1.2 Flutter 웹이 적합한 앱 유형#

Flutter 웹은 다음과 같은 유형의 앱에 적합합니다:

앱 유형	설명	적합도
SPA³	그래픽이 풍부하고 인터랙티브한 웹 앱	매우 적합
기존 모바일 앱의 웹 버전	모바일 앱을 웹으로 확장	매우 적합
대시보드	데이터 시각화 및 관리 도구	적합
콘텐츠 중심 웹사이트	블로그, 뉴스 등 텍스트 중심	부적합

주의하세요!
텍스트 중심의 정적 콘텐츠 웹사이트에는 Flutter 웹이 적합하지 않습니다. 이러한 경우 전통적인 웹 기술(HTML, CSS, JavaScript)을 사용하는 것이 좋습니다.

Chapter 2: 웹 개발 환경 설정#

2.1 필수 요구 사항#

Flutter 웹 개발을 위해 다음이 필요합니다:

1
# Flutter SDK 설치 확인
2
flutter --version
3

4
# 웹 개발이 활성화되어 있는지 확인
5
flutter devices

Chrome 브라우저가 설치되어 있어야 합니다.

확인해보세요!
flutter devices 명령어를 실행하면 Chrome이 사용 가능한 기기 목록에 표시되어야 합니다.

2.2 새 웹 프로젝트 생성#

새 Flutter 프로젝트를 생성하면 기본적으로 웹 지원이 포함됩니다:

1
# 새 프로젝트 생성 (웹 포함)
2
flutter create my_web_app
3

4
# 프로젝트 디렉토리로 이동
5
cd my_web_app

2.3 기존 프로젝트에 웹 지원 추가#

기존 Flutter 프로젝트에 웹 지원을 추가하려면:

1
# 기존 프로젝트 디렉토리에서 실행
2
flutter create . --platforms web

이 명령어는 web/ 디렉토리를 생성합니다:

1
my_app/
2
├── web/
3
│   ├── favicon.png
4
│   ├── icons/
5
│   │   ├── Icon-192.png
6
│   │   ├── Icon-512.png
7
│   │   └── Icon-maskable-192.png
8
│   ├── index.html
9
│   └── manifest.json
10
├── lib/
11
│   └── main.dart
12
└── pubspec.yaml

Chapter 3: 웹 앱 실행과 개발#

3.1 개발 서버 실행#

Chrome에서 웹 앱을 실행합니다:

1
# Chrome에서 실행
2
flutter run -d chrome
3

4
# Edge에서 실행 (Windows)
5
flutter run -d edge
6

7
# 웹 서버 모드로 실행 (브라우저 선택 가능)
8
flutter run -d web-server

Hot Reload 지원
Flutter 3.35부터 웹에서도 Hot Reload가 기본적으로 활성화됩니다. r 키를 눌러 Hot Reload를, R 키를 눌러 Hot Restart⁴를 실행할 수 있습니다.

3.2 Hot Reload 비활성화#

특정 상황에서 Hot Reload를 비활성화할 수 있습니다:

1
# 명령줄에서 비활성화
2
flutter run -d chrome --no-web-experimental-hot-reload

VS Code에서 비활성화하려면 launch.json을 수정합니다:

1
{
2
  "configurations": [
3
    {
4
      "name": "Flutter for web (hot reload disabled)",
5
      "type": "dart",
6
      "request": "launch",
7
      "program": "lib/main.dart",
8
      "args": [
9
        "-d",
10
        "chrome",
11
        "--no-web-experimental-hot-reload"
12
      ]
13
    }
14
  ]
15
}

3.3 웹 전용 코드 작성#

플랫폼별 코드를 작성할 때는 kIsWeb 상수를 사용합니다:

1
import 'package:flutter/foundation.dart';
2
import 'package:flutter/material.dart';
3

4
class PlatformAwareWidget extends StatelessWidget {
5
  const PlatformAwareWidget({super.key});
6

7
  @override
8
  Widget build(BuildContext context) {
9
    if (kIsWeb) {
10
      return const WebSpecificWidget();
11
    } else {
12
      return const MobileSpecificWidget();
13
    }
14
  }
15
}
16

17
class WebSpecificWidget extends StatelessWidget {
18
  const WebSpecificWidget({super.key});
19

20
  @override
21
  Widget build(BuildContext context) {
22
    return Container(
23
      padding: const EdgeInsets.all(20),
24
      child: const Text(
25
        '웹 브라우저에서 실행 중입니다.',
26
        style: TextStyle(fontSize: 24),
27
      ),
28
    );
29
  }
30
}
31

32
class MobileSpecificWidget extends StatelessWidget {
33
  const MobileSpecificWidget({super.key});
34

35
  @override
36
  Widget build(BuildContext context) {
37
    return Container(
38
      padding: const EdgeInsets.all(20),
39
      child: const Text(
40
        '모바일 기기에서 실행 중입니다.',
41
        style: TextStyle(fontSize: 24),
42
      ),
43
    );
44
  }
45
}

Chapter 4: 웹 렌더러 이해하기#

4.1 렌더러 종류#

Flutter 웹은 두 가지 렌더러를 지원합니다:

렌더러	설명	다운로드 크기
CanvasKit	Skia⁵를 WebAssembly로 컴파일	약 1.5MB
Skwasm	더 컴팩트한 Skia 버전, 멀티스레드 지원	약 1.1MB

4.2 빌드 모드와 렌더러#

1
빌드 모드          사용 가능한 렌더러
2
─────────────────────────────────────────
3
기본 모드          CanvasKit만 사용
4
WebAssembly 모드   Skwasm (우선) → CanvasKit (폴백)

렌더러 선택 기준

CanvasKit: 모든 최신 브라우저와 호환, 안정적인 성능

Skwasm: 더 빠른 시작 시간, 더 나은 프레임 성능 (WasmGC⁶ 지원 브라우저에서)

4.3 멀티스레드 렌더링#

Skwasm 렌더러는 멀티스레드 렌더링을 지원합니다. 이를 활성화하려면 서버가 다음 보안 헤더를 제공해야 합니다:

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

주의하세요!
멀티스레드 렌더링을 위해서는 SharedArrayBuffer⁷ 보안 요구 사항을 충족해야 합니다. 이 요구 사항을 충족하지 않으면 단일 스레드 모드로 실행됩니다.

Chapter 5: 웹 앱 빌드#

5.1 기본 빌드#

릴리스용 웹 앱을 빌드합니다:

1
# 기본 빌드 (CanvasKit 렌더러 사용)
2
flutter build web

빌드 결과는 build/web/ 디렉토리에 생성됩니다:

1
build/web/
2
├── assets/
3
│   ├── AssetManifest.json
4
│   ├── FontManifest.json
5
│   ├── fonts/
6
│   └── packages/
7
├── canvaskit/
8
├── favicon.png
9
├── flutter.js
10
├── flutter_bootstrap.js
11
├── flutter_service_worker.js
12
├── icons/
13
├── index.html
14
├── main.dart.js
15
└── manifest.json

5.2 WebAssembly 빌드#

더 나은 성능을 위해 WebAssembly 모드로 빌드합니다:

1
# WebAssembly 빌드
2
flutter build web --wasm

WebAssembly 빌드 요구 사항
WebAssembly 빌드를 사용하려면:

새로운 JS Interop 사용: dart:js_interop 라이브러리 사용

새로운 Web API 사용: package:web 패키지 사용 (기존 dart:html 대신)

숫자 호환성: Dart VM과 동일한 숫자 동작 보장

5.3 빌드 최적화 옵션#

1
# 트리 쉐이킹 아이콘 사용
2
flutter build web --tree-shake-icons
3

4
# 소스 맵 생성 비활성화 (파일 크기 감소)
5
flutter build web --no-source-maps
6

7
# 복합 최적화
8
flutter build web --wasm --tree-shake-icons --no-source-maps

Chapter 6: 웹 앱 초기화 커스터마이징#

6.1 index.html 수정#

web/index.html 파일을 수정하여 앱 초기화를 커스터마이징할 수 있습니다:

1
<!DOCTYPE html>
2
<html>
3
<head>
4
  <meta charset="UTF-8">
5
  <meta content="IE=Edge" http-equiv="X-UA-Compatible">
6
  <meta name="description" content="My Flutter Web App">
7

8
  <!-- iOS 지원 -->
9
  <meta name="apple-mobile-web-app-capable" content="yes">
10
  <meta name="apple-mobile-web-app-status-bar-style" content="black">
11
  <meta name="apple-mobile-web-app-title" content="My App">
12

13
  <!-- Favicon -->
14
  <link rel="apple-touch-icon" href="icons/Icon-192.png">
15
  <link rel="icon" type="image/png" href="favicon.png"/>
16

17
  <title>My Flutter Web App</title>
18
  <link rel="manifest" href="manifest.json">
19
</head>
20
<body>
21
  <!-- 로딩 인디케이터 -->
22
  <div id="loading">
23
    <style>
24
      #loading {
25
        display: flex;
26
        justify-content: center;
27
        align-items: center;
28
        height: 100vh;
29
        background-color: #ffffff;
30
      }
31
      .spinner {
32
        width: 50px;
33
        height: 50px;
34
        border: 3px solid #f3f3f3;
35
        border-top: 3px solid #3498db;
36
        border-radius: 50%;
37
        animation: spin 1s linear infinite;
38
      }
39
      @keyframes spin {
40
        0% { transform: rotate(0deg); }
41
        100% { transform: rotate(360deg); }
42
      }
43
    </style>
44
    <div class="spinner"></div>
45
  </div>
46

47
  <script src="flutter_bootstrap.js" async></script>
48
</body>
49
</html>

6.2 렌더러 수동 선택#

특정 렌더러를 강제로 사용하도록 설정할 수 있습니다:

1
<body>
2
  <script>
3
    {{flutter_js}}
4
    {{flutter_build_config}}
5

6
    // 렌더러 선택 로직
7
    const useCanvasKit = !navigator.userAgent.includes('Chrome');
8

9
    const config = {
10
      renderer: useCanvasKit ? "canvaskit" : "skwasm",
11
    };
12

13
    _flutter.loader.load({
14
      config: config,
15
    });
16
  </script>
17
</body>

6.3 스플래시 화면 구현#

앱 로딩 중 스플래시 화면을 표시합니다:

1
<body>
2
  <div id="splash" style="position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
3
    <img src="icons/Icon-192.png" alt="Loading..." style="width: 100px; height: 100px;">
4
  </div>
5

6
  <script>
7
    {{flutter_js}}
8
    {{flutter_build_config}}
9

10
    _flutter.loader.load({
11
      onEntrypointLoaded: function(engineInitializer) {
12
        engineInitializer.initializeEngine().then(function(appRunner) {
13
          // 스플래시 화면 제거
14
          document.getElementById('splash').remove();
15
          appRunner.runApp();
16
        });
17
      }
18
    });
19
  </script>
20
</body>

Chapter 7: 웹 디버깅#

7.1 Flutter DevTools 사용#

Flutter DevTools를 사용하여 웹 앱을 디버깅합니다:

1
# DevTools 실행
2
flutter run -d chrome
3
# 실행 후 'd' 키를 눌러 DevTools 열기

DevTools에서 사용할 수 있는 기능:

Widget Inspector: 위젯 트리 검사
Performance: 프레임 분석
Memory: 메모리 사용량 모니터링
Logging: 로그 메시지 확인

7.2 Chrome DevTools 활용#

Chrome DevTools도 함께 사용할 수 있습니다:

1
// 디버그 로그 출력
2
import 'dart:developer' as developer;
3

4
void logMessage(String message) {
5
  developer.log(message, name: 'MyApp');
6
}
7

8
// 브레이크포인트 설정
9
void someFunction() {
10
  debugger(); // Chrome DevTools에서 중단점으로 작동
11
  // 코드 계속...
12
}

7.3 프로파일 빌드#

성능 분석을 위한 프로파일 빌드:

1
# 프로파일 모드로 실행
2
flutter run -d chrome --profile
3

4
# 프로파일 빌드
5
flutter build web --profile

성능 분석 팁
Chrome DevTools의 Performance 탭을 사용하여:

프레임 드롭 분석

렌더링 성능 측정

메모리 누수 감지

를 수행할 수 있습니다.

Chapter 8: 테스트#

8.1 위젯 테스트#

웹 환경을 고려한 위젯 테스트:

1
import 'package:flutter/material.dart';
2
import 'package:flutter_test/flutter_test.dart';
3
import 'package:my_web_app/main.dart';
4

5
void main() {
6
  testWidgets('웹 앱 초기 화면 테스트', (WidgetTester tester) async {
7
    await tester.pumpWidget(const MyApp());
8

9
    expect(find.text('Welcome'), findsOneWidget);
10
    expect(find.byType(ElevatedButton), findsAtLeast(1));
11
  });
12

13
  testWidgets('반응형 레이아웃 테스트', (WidgetTester tester) async {
14
    // 웹 화면 크기 설정
15
    tester.view.physicalSize = const Size(1920, 1080);
16
    tester.view.devicePixelRatio = 1.0;
17

18
    await tester.pumpWidget(const MyApp());
19

20
    // 데스크톱 레이아웃 확인
21
    expect(find.byType(Row), findsAtLeast(1));
22

23
    // 모바일 화면 크기로 변경
24
    tester.view.physicalSize = const Size(375, 812);
25
    await tester.pump();
26

27
    // 모바일 레이아웃 확인
28
    expect(find.byType(Column), findsAtLeast(1));
29

30
    // 리소스 정리
31
    tester.view.resetPhysicalSize();
32
  });
33
}

8.2 통합 테스트#

브라우저에서 통합 테스트를 실행합니다:

1
import 'package:flutter_test/flutter_test.dart';
2
import 'package:integration_test/integration_test.dart';
3
import 'package:my_web_app/main.dart' as app;
4

5
void main() {
6
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
7

8
  testWidgets('전체 앱 플로우 테스트', (WidgetTester tester) async {
9
    app.main();
10
    await tester.pumpAndSettle();
11

12
    // 버튼 클릭
13
    await tester.tap(find.byType(ElevatedButton).first);
14
    await tester.pumpAndSettle();
15

16
    // 결과 확인
17
    expect(find.text('Clicked!'), findsOneWidget);
18
  });
19
}

1
# 웹에서 통합 테스트 실행
2
flutter test integration_test --device-id chrome

Chapter 9: 반응형 웹 디자인#

9.1 반응형 레이아웃 구현#

화면 크기에 따라 레이아웃을 조정합니다:

1
import 'package:flutter/material.dart';
2

3
class ResponsiveLayout extends StatelessWidget {
4
  final Widget mobile;
5
  final Widget tablet;
6
  final Widget desktop;
7

8
  const ResponsiveLayout({
9
    super.key,
10
    required this.mobile,
11
    required this.tablet,
12
    required this.desktop,
13
  });
14

15
  static bool isMobile(BuildContext context) =>
16
      MediaQuery.of(context).size.width < 600;
17

18
  static bool isTablet(BuildContext context) =>
19
      MediaQuery.of(context).size.width >= 600 &&
20
      MediaQuery.of(context).size.width < 1200;
21

22
  static bool isDesktop(BuildContext context) =>
23
      MediaQuery.of(context).size.width >= 1200;
24

25
  @override
26
  Widget build(BuildContext context) {
27
    return LayoutBuilder(
28
      builder: (context, constraints) {
29
        if (constraints.maxWidth >= 1200) {
30
          return desktop;
31
        } else if (constraints.maxWidth >= 600) {
32
          return tablet;
33
        } else {
34
          return mobile;
35
        }
36
      },
37
    );
38
  }
39
}

9.2 반응형 위젯 예제#

1
class MyHomePage extends StatelessWidget {
2
  const MyHomePage({super.key});
3

4
  @override
5
  Widget build(BuildContext context) {
6
    return Scaffold(
7
      appBar: AppBar(
8
        title: const Text('반응형 웹 앱'),
9
      ),
10
      body: ResponsiveLayout(
11
        mobile: const MobileLayout(),
12
        tablet: const TabletLayout(),
13
        desktop: const DesktopLayout(),
14
      ),
15
    );
16
  }
17
}
18

19
class DesktopLayout extends StatelessWidget {
20
  const DesktopLayout({super.key});
21

22
  @override
23
  Widget build(BuildContext context) {
24
    return Row(
25
      children: [
26
        // 사이드바
27
        NavigationRail(
28
          destinations: const [
29
            NavigationRailDestination(
30
              icon: Icon(Icons.home),
31
              label: Text('Home'),
32
            ),
33
            NavigationRailDestination(
34
              icon: Icon(Icons.settings),
35
              label: Text('Settings'),
36
            ),
37
          ],
38
          selectedIndex: 0,
39
        ),
40
        const VerticalDivider(thickness: 1, width: 1),
41
        // 메인 콘텐츠
42
        Expanded(
43
          child: Center(
44
            child: ConstrainedBox(
45
              constraints: const BoxConstraints(maxWidth: 1200),
46
              child: const ContentArea(),
47
            ),
48
          ),
49
        ),
50
      ],
51
    );
52
  }
53
}
54

55
class TabletLayout extends StatelessWidget {
56
  const TabletLayout({super.key});
57

58
  @override
59
  Widget build(BuildContext context) {
60
    return Row(
61
      children: [
62
        NavigationRail(
63
          destinations: const [
64
            NavigationRailDestination(
65
              icon: Icon(Icons.home),
66
              label: Text('Home'),
67
            ),
68
            NavigationRailDestination(
69
              icon: Icon(Icons.settings),
70
              label: Text('Settings'),
71
            ),
72
          ],
73
          selectedIndex: 0,
74
          labelType: NavigationRailLabelType.none,
75
        ),
76
        const Expanded(child: ContentArea()),
77
      ],
78
    );
79
  }
80
}
81

82
class MobileLayout extends StatelessWidget {
83
  const MobileLayout({super.key});
84

85
  @override
86
  Widget build(BuildContext context) {
87
    return Scaffold(
88
      body: const ContentArea(),
89
      bottomNavigationBar: BottomNavigationBar(
90
        items: const [
91
          BottomNavigationBarItem(
92
            icon: Icon(Icons.home),
93
            label: 'Home',
94
          ),
95
          BottomNavigationBarItem(
96
            icon: Icon(Icons.settings),
97
            label: 'Settings',
98
          ),
99
        ],
100
      ),
101
    );
102
  }
103
}
104

105
class ContentArea extends StatelessWidget {
106
  const ContentArea({super.key});
107

108
  @override
109
  Widget build(BuildContext context) {
110
    return ListView.builder(
111
      padding: const EdgeInsets.all(16),
112
      itemCount: 20,
113
      itemBuilder: (context, index) {
114
        return Card(
115
          margin: const EdgeInsets.only(bottom: 12),
116
          child: ListTile(
117
            leading: CircleAvatar(child: Text('${index + 1}')),
118
            title: Text('Item ${index + 1}'),
119
            subtitle: const Text('This is a sample item'),
120
          ),
121
        );
122
      },
123
    );
124
  }
125
}

마무리#

이번 튜토리얼에서 Flutter 웹 앱 개발의 기초를 배웠습니다.

핵심 정리#

프로젝트 설정: flutter create로 웹 지원 프로젝트를 쉽게 생성할 수 있습니다
개발 서버: flutter run -d chrome으로 Hot Reload와 함께 개발할 수 있습니다
렌더러: CanvasKit(기본)과 Skwasm(WebAssembly) 중 선택할 수 있습니다
빌드: flutter build web 또는 flutter build web --wasm으로 배포용 빌드를 생성합니다
반응형 디자인: LayoutBuilder와 MediaQuery를 활용하여 반응형 레이아웃을 구현합니다

다음 단계#

WebAssembly 심화 학습 (튜토리얼 60편)
웹 앱 배포 방법 (튜토리얼 64편)

참고 자료#

렌더러(Renderer)는 UI를 화면에 그리는 역할을 담당하는 구성 요소입니다. ↩
WebAssembly(Wasm)는 웹 브라우저에서 실행할 수 있는 저수준 바이너리 명령어 형식으로, JavaScript보다 빠른 실행 속도를 제공합니다. ↩
SPA(Single Page Application)는 페이지 전환 없이 동적으로 콘텐츠를 업데이트하는 웹 애플리케이션입니다. ↩
Hot Restart는 앱 상태를 초기화하면서 전체 앱을 다시 시작하는 기능입니다. Hot Reload보다 더 많은 변경 사항을 반영할 수 있습니다. ↩
Skia는 Google이 개발한 오픈소스 2D 그래픽 라이브러리로, Chrome, Android, Flutter 등에서 사용됩니다. ↩
WasmGC(WebAssembly Garbage Collection)는 WebAssembly에서 가비지 컬렉션을 지원하는 확장 기능입니다. ↩
SharedArrayBuffer는 여러 웹 워커 간에 메모리를 공유할 수 있게 해주는 JavaScript 객체입니다. ↩

Flutter 튜토리얼 59편: 웹 앱 개발

학습 목표#

Chapter 1: Flutter 웹 지원 이해하기#

1.1 Flutter 웹의 특징#

1.2 Flutter 웹이 적합한 앱 유형#

Chapter 2: 웹 개발 환경 설정#

2.1 필수 요구 사항#

2.2 새 웹 프로젝트 생성#

2.3 기존 프로젝트에 웹 지원 추가#

Chapter 3: 웹 앱 실행과 개발#

3.1 개발 서버 실행#

3.2 Hot Reload 비활성화#

3.3 웹 전용 코드 작성#

Chapter 4: 웹 렌더러 이해하기#

4.1 렌더러 종류#

4.2 빌드 모드와 렌더러#

4.3 멀티스레드 렌더링#

Chapter 5: 웹 앱 빌드#

5.1 기본 빌드#

5.2 WebAssembly 빌드#

5.3 빌드 최적화 옵션#

Chapter 6: 웹 앱 초기화 커스터마이징#

6.1 index.html 수정#

6.2 렌더러 수동 선택#

6.3 스플래시 화면 구현#

Chapter 7: 웹 디버깅#

7.1 Flutter DevTools 사용#

7.2 Chrome DevTools 활용#

7.3 프로파일 빌드#

Chapter 8: 테스트#

8.1 위젯 테스트#

8.2 통합 테스트#

Chapter 9: 반응형 웹 디자인#

9.1 반응형 레이아웃 구현#

9.2 반응형 위젯 예제#

마무리#

핵심 정리#

다음 단계#

참고 자료#

Footnotes#

공유

목차