Flutter 튜토리얼 60편: WebAssembly와 웹 고급

개요#

Flutter 웹 앱의 성능을 극대화하고 고급 기능을 활용하는 방법을 알아봅니다. WebAssembly¹를 통한 네이티브 수준의 성능, 앱 초기화 커스터마이징, 기존 웹 앱에 Flutter 임베딩, 그리고 웹 이미지 처리까지 살펴보겠습니다.

graph TB subgraph "Flutter 웹 고급 기능" A[WebAssembly 컴파일] --> B[네이티브 성능] C[앱 초기화 커스터마이징] --> D[로딩 최적화] E[Flutter 임베딩] --> F[하이브리드 앱] G[웹 이미지 처리] --> H[CORS 해결] end

1. WebAssembly (Wasm) 지원#

Why: 왜 WebAssembly를 사용하나요?#

WebAssembly는 JavaScript보다 훨씬 빠른 실행 속도를 제공합니다. 복잡한 애니메이션, 대량의 데이터 처리, 게임 등 성능이 중요한 웹 앱에서 큰 이점을 얻을 수 있습니다.

What: WebAssembly란 무엇인가요?#

Flutter는 Dart 코드를 WebAssembly로 컴파일하여 브라우저에서 실행할 수 있습니다. 이를 통해 네이티브에 가까운 성능을 웹에서도 경험할 수 있습니다.

특징	JavaScript	WebAssembly
실행 속도	인터프리터/JIT	네이티브에 가까움
파일 크기	텍스트 기반	바이너리 (압축)
시작 시간	파싱 필요	즉시 실행
메모리	가비지 컬렉션	수동 관리 가능

How: WebAssembly 빌드 방법#

1단계: Flutter 버전 확인#

1
# Flutter 3.24 이상 필요
2
flutter upgrade
3
flutter --version

2단계: 의존성 호환성 확인#

WebAssembly 컴파일을 위해서는 새로운 JS interop² 라이브러리를 사용해야 합니다.

1
# pubspec.yaml - 호환되는 라이브러리 사용
2
dependencies:
3
  web: ^0.5.0  # dart:html 대신 사용

1
// 기존 (Wasm 미지원)
2
import 'dart:html';
3

4
// 새로운 방식 (Wasm 지원)
5
import 'package:web/web.dart';
6
import 'dart:js_interop';

3단계: index.html 업데이트#

1
# web 디렉토리 재생성 (최신 초기화 방식 적용)
2
flutter create . --platforms web

4단계: Wasm으로 실행/빌드#

1
# 개발 모드 실행
2
flutter run -d chrome --wasm
3

4
# 프로덕션 빌드
5
flutter build web --wasm

Wasm 실행 여부 확인#

1
class WasmChecker extends StatelessWidget {
2
  @override
3
  Widget build(BuildContext context) {
4
    // 빌드 시점에 결정되는 환경 변수 (권장)
5
    const isWasm = bool.fromEnvironment('dart.tool.dart2wasm');
6

7
    // 또는 런타임에 확인 (대안)
8
    // final isWasm = identical(double.nan, double.nan);
9

10
    return Center(
11
      child: Text(
12
        isWasm ? 'WebAssembly로 실행 중' : 'JavaScript로 실행 중',
13
        style: TextStyle(fontSize: 24),
14
      ),
15
    );
16
  }
17
}

Watch out: 주의사항#

멀티스레딩을 위한 HTTP 헤더 설정#

Wasm 멀티스레딩을 사용하려면 서버에서 특정 HTTP 헤더를 설정해야 합니다.

헤더	값
`Cross-Origin-Embedder-Policy`	`credentialless` 또는 `require-corp`
`Cross-Origin-Opener-Policy`	`same-origin`

브라우저 호환성#

graph LR A[WasmGC 지원] --> B[Chrome 119+] A --> C[Edge 119+] D[현재 미지원] --> E[Firefox] D --> F[Safari] D --> G[iOS 모든 브라우저]

2. 웹 앱 초기화 커스터마이징#

Why: 왜 초기화를 커스터마이징하나요?#

기본 초기화 대신 커스텀 로직을 추가하여 로딩 화면 표시, 설정 변경, 서비스 워커 제어 등을 할 수 있습니다.

What: 초기화 토큰이란?#

Flutter 빌드 시 특별한 토큰들이 실제 코드로 대체됩니다.

토큰	설명
`{{flutter_js}}`	FlutterLoader를 사용 가능하게 하는 JS 코드
`{{flutter_build_config}}`	빌드 메타데이터 설정
`{{flutter_service_worker_version}}`	서비스 워커 버전 번호
`{{flutter_bootstrap_js}}`	부트스트랩 스크립트 전체 내용

How: 커스텀 초기화 구현#

기본 부트스트랩 스크립트#

1
<!DOCTYPE html>
2
<html>
3
<head>
4
  <meta charset="UTF-8">
5
  <title>My Flutter App</title>
6
</head>
7
<body>
8
  <script>
9
    {{flutter_bootstrap_js}}
10
  </script>
11
</body>
12
</html>

커스텀 부트스트랩 스크립트#

1
{{flutter_js}}
2
{{flutter_build_config}}
3

4
// 로딩 표시
5
const loading = document.createElement('div');
6
loading.id = 'loading';
7
loading.innerHTML = '<h1>로딩 중...</h1>';
8
document.body.appendChild(loading);
9

10
_flutter.loader.load({
11
  onEntrypointLoaded: async function(engineInitializer) {
12
    loading.innerHTML = '<h1>엔진 초기화 중...</h1>';
13

14
    const appRunner = await engineInitializer.initializeEngine();
15

16
    loading.innerHTML = '<h1>앱 시작 중...</h1>';
17
    await appRunner.runApp();
18

19
    // 로딩 요소 제거
20
    loading.remove();
21
  }
22
});

설정 옵션#

1
_flutter.loader.load({
2
  config: {
3
    // 렌더러 지정 (canvaskit 또는 skwasm)
4
    renderer: 'canvaskit',
5

6
    // CanvasKit 설정
7
    canvasKitBaseUrl: '/canvaskit/',
8
    canvasKitVariant: 'auto', // auto, full, chromium
9
    canvasKitForceCpuOnly: false,
10
    canvasKitMaximumSurfaces: 8,
11

12
    // Wasm 싱글스레드 강제 (호환성용)
13
    forceSingleThreadedSkwasm: true,
14

15
    // 에셋 경로 설정 (CDN 사용 시)
16
    assetBase: 'https://cdn.example.com/assets/',
17

18
    // 디버깅
19
    debugShowSemanticNodes: false,
20
  }
21
});

URL 파라미터로 렌더러 선택#

1
{{flutter_js}}
2
{{flutter_build_config}}
3

4
const searchParams = new URLSearchParams(window.location.search);
5
const renderer = searchParams.get('renderer');
6
const userConfig = renderer ? { 'renderer': renderer } : {};
7

8
_flutter.loader.load({
9
  config: userConfig,
10
});
11

12
// 사용: https://myapp.com/?renderer=skwasm

3. 기존 웹 앱에 Flutter 임베딩#

Why: 왜 Flutter를 임베딩하나요?#

기존 웹 사이트의 일부 섹션만 Flutter로 구현하거나, 점진적으로 Flutter로 마이그레이션할 때 유용합니다.

What: 임베딩 모드의 종류#

graph TB subgraph "임베딩 방식" A[전체 페이지 모드] --> B[Flutter가 전체 화면 제어] C[iframe 임베딩] --> D[격리된 Flutter 앱] E[임베디드 모드] --> F[특정 요소에 렌더링] E --> G[멀티뷰 지원] end

모드	설명	사용 사례
전체 페이지	기본 모드, 전체 화면 사용	독립 웹 앱
iframe	별도 문서로 격리	위젯 형태 삽입
임베디드	HTML 요소에 직접 렌더링	하이브리드 앱

How: 임베딩 구현 방법#

iframe 임베딩 (가장 간단)#

1
<!-- 호스트 페이지 -->
2
<iframe
3
  src="https://my-flutter-app.com/index.html"
4
  width="800"
5
  height="600"
6
  style="border: none;">
7
</iframe>

멀티뷰 임베디드 모드#

JavaScript 설정:

1
{{flutter_js}}
2
{{flutter_build_config}}
3

4
_flutter.loader.load({
5
  onEntrypointLoaded: async function(engineInitializer) {
6
    let engine = await engineInitializer.initializeEngine({
7
      multiViewEnabled: true, // 임베디드 모드 활성화
8
    });
9

10
    let app = await engine.runApp();
11

12
    // 전역으로 노출하여 호스트 앱에서 사용
13
    window.flutterApp = app;
14
  }
15
});

호스트 페이지에서 뷰 관리:

1
// 뷰 추가
2
let viewId = window.flutterApp.addView({
3
  hostElement: document.querySelector('#flutter-container'),
4
  initialData: {
5
    greeting: '안녕하세요!',
6
    userId: 12345,
7
  }
8
});
9

10
// 뷰 제거
11
window.flutterApp.removeView(viewId);

Dart에서 멀티뷰 처리:

1
import 'dart:ui' show FlutterView;
2
import 'package:flutter/widgets.dart';
3

4
void main() {
5
  runWidget(
6
    MultiViewApp(
7
      viewBuilder: (BuildContext context) => const MyApp(),
8
    ),
9
  );
10
}
11

12
/// 각 뷰에 대해 위젯을 생성하는 래퍼
13
class MultiViewApp extends StatefulWidget {
14
  const MultiViewApp({super.key, required this.viewBuilder});
15

16
  final WidgetBuilder viewBuilder;
17

18
  @override
19
  State<MultiViewApp> createState() => _MultiViewAppState();
20
}
21

22
class _MultiViewAppState extends State<MultiViewApp>
23
    with WidgetsBindingObserver {
24
  Map<Object, Widget> _views = {};
25

26
  @override
27
  void initState() {
28
    super.initState();
29
    WidgetsBinding.instance.addObserver(this);
30
    _updateViews();
31
  }
32

33
  @override
34
  void didChangeMetrics() {
35
    _updateViews();
36
  }
37

38
  void _updateViews() {
39
    final newViews = <Object, Widget>{};
40

41
    for (final view in WidgetsBinding.instance.platformDispatcher.views) {
42
      newViews[view.viewId] = _views[view.viewId] ??
43
        View(
44
          view: view,
45
          child: Builder(builder: widget.viewBuilder),
46
        );
47
    }
48

49
    setState(() => _views = newViews);
50
  }
51

52
  @override
53
  void dispose() {
54
    WidgetsBinding.instance.removeObserver(this);
55
    super.dispose();
56
  }
57

58
  @override
59
  Widget build(BuildContext context) {
60
    return ViewCollection(views: _views.values.toList());
61
  }
62
}

뷰 식별 및 초기 데이터#

1
class MyWidget extends StatelessWidget {
2
  @override
3
  Widget build(BuildContext context) {
4
    // 현재 뷰 ID 가져오기
5
    final viewId = View.of(context).viewId;
6

7
    // 초기 데이터 가져오기 (JS interop 필요)
8
    // final initialData = ui_web.views.getInitialData(viewId);
9

10
    return Center(
11
      child: Text('뷰 ID: $viewId'),
12
    );
13
  }
14
}

hostElement로 단일 뷰 임베딩#

1
// 멀티뷰 없이 특정 요소에 렌더링
2
_flutter.loader.load({
3
  config: {
4
    hostElement: document.getElementById('flutter_host'),
5
  }
6
});

1
<div id="flutter_host" style="width: 100%; height: 400px;"></div>

4. 웹 이미지 표시#

Why: 왜 웹 이미지 처리가 특별한가요?#

웹 브라우저의 보안 정책(CORS³)으로 인해 다른 도메인의 이미지를 직접 처리하는 데 제한이 있습니다.

What: 이미지 표시 방식 비교#

방식	장점	단점
`<img>` 태그	캐싱, 최적화 자동	픽셀 접근 불가
Canvas drawImage	픽셀 조작 가능	CORS 제한
WebGL	최고 성능, 셰이더	복잡한 구현

CORS 문제 이해하기#

sequenceDiagram participant App as Flutter 앱 participant Browser as 브라우저 participant Server as 이미지 서버 App->>Browser: 이미지 요청 Browser->>Server: HTTP 요청 Server->>Browser: 응답 (CORS 헤더 확인) alt CORS 허용 Browser->>App: 이미지 데이터 전달 else CORS 거부 Browser->>App: 차단됨 end

How: CORS 문제 해결 방법#

1. 같은 출처 이미지 사용#

1
// 에셋 이미지
2
Image.asset('assets/images/photo.png')
3

4
// 같은 도메인 네트워크 이미지
5
Image.network('/images/photo.png')
6

7
// 메모리 이미지
8
Image.memory(bytes)

2. CORS 활성화된 CDN 사용#

Firebase Hosting 예시:

1
{
2
  "hosting": {
3
    "headers": [
4
      {
5
        "source": "**/*.@(jpg|jpeg|png|gif|webp)",
6
        "headers": [
7
          {
8
            "key": "Access-Control-Allow-Origin",
9
            "value": "*"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

3. CORS 프록시 사용#

1
class ImageProxy {
2
  // CloudFlare Workers나 자체 서버를 통한 프록시
3
  static String getProxiedUrl(String originalUrl) {
4
    return 'https://my-cors-proxy.com/?url=${Uri.encodeComponent(originalUrl)}';
5
  }
6
}
7

8
// 사용
9
Image.network(ImageProxy.getProxiedUrl('https://external-site.com/image.jpg'))

4. HTML 플랫폼 뷰 사용#

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

4
class WebImage extends StatelessWidget {
5
  final String url;
6

7
  const WebImage({super.key, required this.url});
8

9
  @override
10
  Widget build(BuildContext context) {
11
    if (kIsWeb) {
12
      // 웹에서는 HTML img 태그 사용
13
      return HtmlElementView(
14
        viewType: 'img-view-$url',
15
        onPlatformViewCreated: (id) {
16
          // 플랫폼 뷰 생성 시 처리
17
        },
18
      );
19
    }
20

21
    // 다른 플랫폼에서는 일반 Image 사용
22
    return Image.network(url);
23
  }
24
}

Watch out: 주의사항#

보안: 프록시 서버를 사용할 때 신뢰할 수 있는 이미지만 프록시하세요.
성능: HTML 플랫폼 뷰는 Flutter 위젯보다 성능이 낮을 수 있습니다.
캐싱: 네트워크 이미지는 cached_network_image 패키지 사용을 고려하세요.

5. 종합 예제: 고급 웹 앱 설정#

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

4
void main() {
5
  WidgetsFlutterBinding.ensureInitialized();
6

7
  runApp(const AdvancedWebApp());
8
}
9

10
class AdvancedWebApp extends StatelessWidget {
11
  const AdvancedWebApp({super.key});
12

13
  @override
14
  Widget build(BuildContext context) {
15
    return MaterialApp(
16
      title: 'Advanced Web App',
17
      theme: ThemeData(
18
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
19
        useMaterial3: true,
20
      ),
21
      home: const HomePage(),
22
    );
23
  }
24
}
25

26
class HomePage extends StatelessWidget {
27
  const HomePage({super.key});
28

29
  @override
30
  Widget build(BuildContext context) {
31
    return Scaffold(
32
      appBar: AppBar(
33
        title: const Text('Flutter 웹 고급 기능'),
34
      ),
35
      body: ListView(
36
        padding: const EdgeInsets.all(16),
37
        children: [
38
          _buildInfoCard(
39
            '실행 환경',
40
            _getExecutionEnvironment(),
41
            Icons.computer,
42
          ),
43
          const SizedBox(height: 16),
44
          _buildInfoCard(
45
            '렌더러',
46
            kIsWeb ? '웹 렌더러 사용 중' : '네이티브 렌더러',
47
            Icons.brush,
48
          ),
49
          const SizedBox(height: 16),
50
          _buildInfoCard(
51
            'WebAssembly',
52
            _isWasm() ? '활성화됨' : '비활성화됨',
53
            Icons.speed,
54
          ),
55
        ],
56
      ),
57
    );
58
  }
59

60
  String _getExecutionEnvironment() {
61
    if (kIsWeb) {
62
      return '웹 브라우저';
63
    } else if (defaultTargetPlatform == TargetPlatform.android) {
64
      return 'Android';
65
    } else if (defaultTargetPlatform == TargetPlatform.iOS) {
66
      return 'iOS';
67
    } else {
68
      return '데스크톱';
69
    }
70
  }
71

72
  bool _isWasm() {
73
    return const bool.fromEnvironment('dart.tool.dart2wasm');
74
  }
75

76
  Widget _buildInfoCard(String title, String value, IconData icon) {
77
    return Card(
78
      child: ListTile(
79
        leading: Icon(icon, size: 40),
80
        title: Text(title),
81
        subtitle: Text(value),
82
      ),
83
    );
84
  }
85
}

마무리#

이번 튜토리얼에서는 Flutter 웹의 고급 기능들을 살펴보았습니다.

핵심 요약#

기능	핵심 포인트
WebAssembly	`--wasm` 플래그로 빌드, 새로운 JS interop 필요
앱 초기화	`flutter_bootstrap.js` 커스터마이징
Flutter 임베딩	`multiViewEnabled`로 멀티뷰 지원
웹 이미지	CORS 정책 이해 및 우회 방법

다음 단계#

61편에서는 데스크톱 앱 개발을 다룹니다.
실제 프로젝트에 WebAssembly를 적용해보세요.
기존 웹사이트에 Flutter 위젯을 임베딩해보세요.

참고 자료#

WebAssembly (Wasm): 웹 브라우저에서 실행되는 이진 명령어 형식으로, JavaScript보다 훨씬 빠른 실행 속도를 제공합니다. ↩
JS interop: Dart 코드에서 JavaScript 코드와 상호작용하기 위한 인터페이스입니다. ↩
CORS (Cross-Origin Resource Sharing): 웹 브라우저가 다른 출처의 리소스에 대한 접근을 제어하는 보안 메커니즘입니다. ↩

Flutter 튜토리얼 60편: WebAssembly와 웹 고급

개요#

1. WebAssembly (Wasm) 지원#

Why: 왜 WebAssembly를 사용하나요?#

What: WebAssembly란 무엇인가요?#

How: WebAssembly 빌드 방법#

1단계: Flutter 버전 확인#

2단계: 의존성 호환성 확인#

3단계: index.html 업데이트#

4단계: Wasm으로 실행/빌드#

Wasm 실행 여부 확인#

Watch out: 주의사항#

멀티스레딩을 위한 HTTP 헤더 설정#

브라우저 호환성#

2. 웹 앱 초기화 커스터마이징#

Why: 왜 초기화를 커스터마이징하나요?#

What: 초기화 토큰이란?#

How: 커스텀 초기화 구현#

기본 부트스트랩 스크립트#

커스텀 부트스트랩 스크립트#

설정 옵션#

URL 파라미터로 렌더러 선택#

3. 기존 웹 앱에 Flutter 임베딩#

Why: 왜 Flutter를 임베딩하나요?#

What: 임베딩 모드의 종류#

How: 임베딩 구현 방법#

iframe 임베딩 (가장 간단)#

멀티뷰 임베디드 모드#

뷰 식별 및 초기 데이터#

hostElement로 단일 뷰 임베딩#

4. 웹 이미지 표시#

Why: 왜 웹 이미지 처리가 특별한가요?#

What: 이미지 표시 방식 비교#

CORS 문제 이해하기#

How: CORS 문제 해결 방법#

1. 같은 출처 이미지 사용#

2. CORS 활성화된 CDN 사용#

3. CORS 프록시 사용#

4. HTML 플랫폼 뷰 사용#

Watch out: 주의사항#

5. 종합 예제: 고급 웹 앱 설정#

마무리#

핵심 요약#

다음 단계#

참고 자료#

Footnotes#

공유

목차