Flutter 튜토리얼 20편: 에셋과 이미지 처리

요약#

핵심 요지#

문제 정의: 앱에서 이미지와 데이터 파일을 효율적으로 관리하지 않으면 메모리 부족과 성능 저하가 발생한다.
핵심 주장: Flutter의 에셋 시스템과 해상도 인식 기능을 활용하면 다양한 기기에서 최적화된 리소스를 제공할 수 있다.
주요 근거: Image.asset()¹으로 번들 이미지를 로드하고, Image.network()²로 원격 이미지를 가져오며, cached_network_image³로 캐싱을 적용한다.
실무 기준: 4K 이미지는 30MB 메모리를 사용하므로, cacheWidth/cacheHeight로 메모리 사용량을 최적화한다.
한계: 지원하지 않는 이미지 포맷은 플랫폼별 처리가 필요하다.

문서가 설명하는 범위#

pubspec.yaml에서 에셋을 등록하는 방법
해상도별 이미지 변형(variant) 관리
로컬과 네트워크 이미지 로딩
캐싱과 메모리 최적화 전략

읽는 시간: 12분 | 난이도: 초급

참고 자료#

Adding assets and images - 에셋 및 이미지 공식 가이드
Image class - Image 위젯 API 문서
cached_network_image - 네트워크 이미지 캐싱 패키지

문제 상황#

앱을 만들 때 이미지, 아이콘, JSON 데이터 같은 정적 파일이 필요합니다. 이런 파일들을 효율적으로 관리하지 않으면 여러 문제가 발생합니다.

에셋 관리의 어려움#

1
문제 1: 기기마다 화면 밀도가 다름 → 이미지가 흐리거나 너무 큼
2
문제 2: 네트워크 이미지를 매번 다운로드 → 데이터 낭비, 느린 로딩
3
문제 3: 고해상도 이미지 무분별 사용 → 메모리 부족, 앱 크래시
4
문제 4: 에셋 경로 하드코딩 → 오타로 인한 런타임 에러

해결 방법#

Flutter는 체계적인 에셋 관리 시스템을 제공합니다. 해상도 인식 이미지, 효율적인 번들링, 다양한 이미지 로딩 방식을 지원합니다.

챕터 1: pubspec.yaml에 에셋 등록하기#

Why#

NOTE
에셋을 앱에서 사용하려면 먼저 Flutter에게 어떤 파일을 번들에 포함할지 알려야 합니다.
pubspec.yaml⁴에 등록하지 않은 파일은 빌드에서 제외됩니다.
1
프로젝트 파일 → pubspec.yaml 등록 → 빌드 시 번들에 포함 → 런타임에 로드 가능

What#

NOTE
에셋은 pubspec.yaml의 flutter 섹션 아래 assets 키에 등록합니다.
개별 파일이나 디렉토리 단위로 지정할 수 있습니다.

How#

TIP

개별 파일 등록

1
flutter:
2
  assets:
3
    - assets/my_icon.png
4
    - assets/background.png
5
    - assets/data/config.json

디렉토리 전체 등록

1
flutter:
2
  assets:
3
    - assets/images/
4
    - assets/data/

디렉토리로 등록하면 해당 폴더의 모든 파일이 포함됩니다.

권장 프로젝트 구조

1
my_app/
2
├── assets/
3
│   ├── images/
4
│   │   ├── logo.png
5
│   │   ├── 2.0x/
6
│   │   │   └── logo.png
7
│   │   └── 3.0x/
8
│   │       └── logo.png
9
│   ├── icons/
10
│   │   └── menu.svg
11
│   └── data/
12
│       └── config.json
13
├── lib/
14
│   └── main.dart
15
└── pubspec.yaml

Watch out#

WARNING
pubspec.yaml에서 들여쓰기가 중요합니다.
assets:는 flutter: 아래에 정확히 2칸 들여쓰기해야 합니다.
1
# 올바른 예시
2
flutter:
3
  assets:
4
    - assets/images/
5

6
# 잘못된 예시 - 에러 발생
7
flutter:
8
assets:  # 들여쓰기 없음
9
  - assets/images/
디렉토리 끝에 /를 붙이면 해당 디렉토리의 파일만 포함됩니다. 하위 디렉토리는 포함되지 않습니다.

결론: pubspec.yaml에 에셋을 등록해야 앱 번들에 포함되어 런타임에 사용할 수 있습니다.

챕터 2: 해상도별 이미지 변형 관리#

Why#

NOTE
기기마다 화면 픽셀 밀도가 다릅니다.
저해상도 이미지를 고밀도 화면에 표시하면 흐릿하게 보이고, 고해상도 이미지만 사용하면 메모리를 낭비합니다.
graph LR A[1.0x: mdpi 기준] --> B[1.5x: hdpi] B --> C[2.0x: xhdpi] C --> D[3.0x: xxhdpi] D --> E[4.0x: xxxhdpi]

What#

NOTE
Flutter는 기기의 devicePixelRatio⁵에 따라 적절한 해상도의 이미지를 자동으로 선택합니다.
해상도별 변형은 1.5x/, 2.0x/, 3.0x/, 4.0x/ 폴더에 같은 이름으로 저장합니다.

How#

TIP
해상도별 이미지 배치
1
assets/
2
├── images/
3
│   ├── logo.png        # 1.0x (기준, 예: 72×72px)
4
│   ├── 1.5x/
5
│   │   └── logo.png    # 1.5x (108×108px)
6
│   ├── 2.0x/
7
│   │   └── logo.png    # 2.0x (144×144px)
8
│   ├── 3.0x/
9
│   │   └── logo.png    # 3.0x (216×216px)
10
│   └── 4.0x/
11
│       └── logo.png    # 4.0x (288×288px)
pubspec.yaml에는 기준 에셋만 등록
1
flutter:
2
  assets:
3
    - assets/images/logo.png
Flutter가 변형 폴더의 이미지를 자동으로 번들에 포함합니다.
사용 시에는 기준 경로만 지정
1
Image.asset('assets/images/logo.png')
기기 화면 밀도에 맞는 이미지가 자동으로 로드됩니다.

Watch out#

WARNING
모든 해상도 변형을 만들 필요는 없습니다.
Flutter는 가장 가까운 해상도를 선택해서 스케일링합니다.
1
// 3.0x 기기에서 3.0x 이미지가 없으면
2
// 2.0x 이미지를 확대하거나 4.0x 이미지를 축소합니다
실무에서는 1.0x, 2.0x, 3.0x 세 가지만 준비해도 충분합니다.

결론: 해상도별 변형을 폴더로 관리하면 Flutter가 기기에 최적화된 이미지를 자동 선택합니다.

챕터 3: Image 위젯으로 이미지 표시#

Why#

NOTE
Flutter에서 이미지를 화면에 표시하려면 Image 위젯을 사용합니다.
이미지 소스에 따라 다른 생성자를 선택합니다.
1
에셋 이미지 → Image.asset()
2
네트워크 이미지 → Image.network()
3
파일 이미지 → Image.file()
4
메모리 이미지 → Image.memory()

What#

NOTE
Image 위젯은 다양한 소스의 이미지를 표시하고, 크기 조절, 정렬, 색상 블렌딩 등 시각적 속성을 제어합니다.
지원 포맷: JPEG, PNG, GIF, Animated GIF, WebP, Animated WebP, BMP, WBMP

How#

TIP

에셋 이미지 로드

1
// 기본 사용법
2
Image.asset('assets/images/logo.png')
3

4
// 크기와 맞춤 지정
5
Image.asset(
6
  'assets/images/background.png',
7
  width: 200,
8
  height: 150,
9
  fit: BoxFit.cover,
10
)
11

12
// 색상 블렌딩 적용
13
Image.asset(
14
  'assets/images/icon.png',
15
  color: Colors.blue,
16
  colorBlendMode: BlendMode.srcIn,
17
)

네트워크 이미지 로드

1
// 기본 사용법
2
Image.network('https://example.com/image.jpg')
3

4
// 로딩 상태 표시
5
Image.network(
6
  'https://example.com/image.jpg',
7
  loadingBuilder: (context, child, loadingProgress) {
8
    if (loadingProgress == null) return child;
9
    return Center(
10
      child: CircularProgressIndicator(
11
        value: loadingProgress.expectedTotalBytes != null
12
            ? loadingProgress.cumulativeBytesLoaded /
13
                loadingProgress.expectedTotalBytes!
14
            : null,
15
      ),
16
    );
17
  },
18
  errorBuilder: (context, error, stackTrace) {
19
    return const Icon(Icons.error);
20
  },
21
)

BoxFit 옵션 비교

BoxFit	설명
`contain`	비율 유지, 전체가 보이도록
`cover`	비율 유지, 영역을 꽉 채움
`fill`	비율 무시, 영역에 맞춤
`fitWidth`	너비에 맞춤
`fitHeight`	높이에 맞춤
`none`	원본 크기
`scaleDown`	큰 경우만 축소

Watch out#

WARNING
Image.network()는 캐싱을 제공하지 않습니다.
화면이 다시 빌드될 때마다 이미지를 다시 다운로드합니다.
1
// 매번 다운로드됨 - 비효율적
2
ListView.builder(
3
  itemBuilder: (context, index) {
4
    return Image.network('https://example.com/image$index.jpg');
5
  },
6
)
캐싱이 필요하면 cached_network_image 패키지를 사용하세요 (챕터 5 참고).

결론: Image 위젯의 적절한 생성자와 BoxFit 옵션을 선택해서 이미지를 표시합니다.

챕터 4: 텍스트 에셋 로드#

Why#

NOTE
앱에서 JSON 설정 파일, 텍스트 데이터, HTML 템플릿 등을 로드해야 할 때가 있습니다.
rootBundle⁶이나 DefaultAssetBundle을 사용해서 텍스트 에셋을 읽습니다.
1
에셋 번들 → 런타임에 문자열로 로드 → JSON 파싱 또는 직접 사용

What#

NOTE
rootBundle은 앱 전역에서 에셋을 로드하고, DefaultAssetBundle은 위젯 컨텍스트에서 에셋을 로드합니다.
DefaultAssetBundle은 테스트와 지역화에 유리합니다.

How#

TIP

rootBundle 사용 (위젯 외부)

1
import 'package:flutter/services.dart' show rootBundle;
2

3
Future<String> loadConfig() async {
4
  return await rootBundle.loadString('assets/data/config.json');
5
}

DefaultAssetBundle 사용 (위젯 내부, 권장)

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

4
  @override
5
  Widget build(BuildContext context) {
6
    return FutureBuilder<String>(
7
      future: DefaultAssetBundle.of(context)
8
          .loadString('assets/data/config.json'),
9
      builder: (context, snapshot) {
10
        if (snapshot.connectionState == ConnectionState.waiting) {
11
          return const CircularProgressIndicator();
12
        }
13
        if (snapshot.hasError) {
14
          return Text('Error: ${snapshot.error}');
15
        }
16
        return Text(snapshot.data ?? '');
17
      },
18
    );
19
  }
20
}

JSON 데이터 파싱

1
import 'dart:convert';
2

3
Future<Map<String, dynamic>> loadJsonConfig(BuildContext context) async {
4
  final jsonString = await DefaultAssetBundle.of(context)
5
      .loadString('assets/data/config.json');
6
  return json.decode(jsonString) as Map<String, dynamic>;
7
}
8

9
// 사용 예시
10
void initConfig(BuildContext context) async {
11
  final config = await loadJsonConfig(context);
12
  print('API URL: ${config['apiUrl']}');
13
  print('Timeout: ${config['timeout']}');
14
}

Watch out#

WARNING

에셋 로드는 비동기 작업입니다.
initState()에서 직접 호출하면 에러가 발생합니다.

1
// 잘못된 사용
2
@override
3
void initState() {
4
  super.initState();
5
  // BuildContext 사용 불가, await 불가
6
  final data = DefaultAssetBundle.of(context).loadString('...');
7
}
8

9
// 올바른 사용
10
@override
11
void didChangeDependencies() {
12
  super.didChangeDependencies();
13
  _loadData();
14
}
15

16
Future<void> _loadData() async {
17
  final data = await DefaultAssetBundle.of(context)
18
      .loadString('assets/data/config.json');
19
  setState(() => _config = data);
20
}

결론: 텍스트 에셋은 DefaultAssetBundle을 사용해서 비동기로 로드합니다.

챕터 5: 네트워크 이미지 캐싱#

Why#

NOTE
네트워크 이미지를 매번 다운로드하면 데이터를 낭비하고 사용자 경험이 나빠집니다.
캐싱을 적용하면 한 번 다운로드한 이미지를 재사용할 수 있습니다.
graph TD A[이미지 요청] --> B{캐시 확인} B -->|있음| C[캐시에서 로드] B -->|없음| D[네트워크 다운로드] D --> E[캐시에 저장] E --> C

What#

NOTE
cached_network_image 패키지는 디스크와 메모리 캐싱을 자동으로 관리합니다.
플레이스홀더, 에러 위젯, 진행률 표시기를 지원합니다.

How#

TIP

패키지 설치

1
dependencies:
2
  cached_network_image: ^3.3.1

기본 사용법

1
import 'package:cached_network_image/cached_network_image.dart';
2

3
CachedNetworkImage(
4
  imageUrl: 'https://example.com/image.jpg',
5
  placeholder: (context, url) => const CircularProgressIndicator(),
6
  errorWidget: (context, url, error) => const Icon(Icons.error),
7
)

진행률 표시

1
CachedNetworkImage(
2
  imageUrl: 'https://example.com/large-image.jpg',
3
  progressIndicatorBuilder: (context, url, progress) {
4
    return CircularProgressIndicator(
5
      value: progress.progress,
6
    );
7
  },
8
  errorWidget: (context, url, error) => const Icon(Icons.error),
9
)

커스텀 이미지 빌더

1
CachedNetworkImage(
2
  imageUrl: 'https://example.com/profile.jpg',
3
  imageBuilder: (context, imageProvider) {
4
    return CircleAvatar(
5
      backgroundImage: imageProvider,
6
      radius: 50,
7
    );
8
  },
9
  placeholder: (context, url) => const CircleAvatar(
10
    radius: 50,
11
    child: Icon(Icons.person),
12
  ),
13
  errorWidget: (context, url, error) => const CircleAvatar(
14
    radius: 50,
15
    child: Icon(Icons.error),
16
  ),
17
)

페이드 애니메이션 설정

1
CachedNetworkImage(
2
  imageUrl: 'https://example.com/image.jpg',
3
  fadeInDuration: const Duration(milliseconds: 300),
4
  fadeOutDuration: const Duration(milliseconds: 300),
5
  fadeInCurve: Curves.easeIn,
6
  fadeOutCurve: Curves.easeOut,
7
)

Watch out#

WARNING

placeholder와 progressIndicatorBuilder는 함께 사용할 수 없습니다.
둘 중 하나만 선택해야 합니다.

1
// 잘못된 사용 - 둘 다 지정하면 progressIndicatorBuilder만 동작
2
CachedNetworkImage(
3
  imageUrl: '...',
4
  placeholder: (context, url) => const Icon(Icons.image),
5
  progressIndicatorBuilder: (context, url, progress) =>
6
      CircularProgressIndicator(value: progress.progress),
7
)
8

9
// 올바른 사용 - 하나만 선택
10
CachedNetworkImage(
11
  imageUrl: '...',
12
  progressIndicatorBuilder: (context, url, progress) =>
13
      CircularProgressIndicator(value: progress.progress),
14
  errorWidget: (context, url, error) => const Icon(Icons.error),
15
)

결론: cached_network_image로 네트워크 이미지를 캐싱하면 성능과 사용자 경험이 개선됩니다.

챕터 6: 이미지 메모리 최적화#

Why#

NOTE
고해상도 이미지는 엄청난 메모리를 사용합니다.
4K 이미지(3840×2160)는 약 30MB의 메모리를 소비합니다.
리스트에서 여러 장을 표시하면 쉽게 메모리 부족이 발생합니다.
1
4K 이미지: 3840 × 2160 × 4bytes = ~30MB
2
작은 썸네일로 캐시: 384 × 216 × 4bytes = ~330KB

What#

NOTE
cacheWidth와 cacheHeight 속성을 사용하면 이미지를 지정한 크기로 디코딩해서 메모리에 저장합니다.
원본 크기 대신 표시 크기에 맞게 캐싱하면 메모리 사용량을 크게 줄일 수 있습니다.

How#

TIP

에셋 이미지 최적화

1
Image.asset(
2
  'assets/images/large-photo.jpg',
3
  cacheWidth: 400,  // 논리적 픽셀 기준
4
  cacheHeight: 300,
5
  fit: BoxFit.cover,
6
)

devicePixelRatio 적용

1
Widget build(BuildContext context) {
2
  final pixelRatio = MediaQuery.devicePixelRatioOf(context);
3
  final displayWidth = 200;  // 화면에 표시할 크기
4

5
  return Image.asset(
6
    'assets/images/photo.jpg',
7
    width: displayWidth.toDouble(),
8
    // 실제 픽셀 크기로 캐시
9
    cacheWidth: (displayWidth * pixelRatio).round(),
10
    fit: BoxFit.cover,
11
  );
12
}

리스트에서 최적화 적용

1
class OptimizedImageList extends StatelessWidget {
2
  final List<String> imageUrls;
3

4
  const OptimizedImageList({super.key, required this.imageUrls});
5

6
  @override
7
  Widget build(BuildContext context) {
8
    final pixelRatio = MediaQuery.devicePixelRatioOf(context);
9

10
    return ListView.builder(
11
      itemCount: imageUrls.length,
12
      itemBuilder: (context, index) {
13
        return CachedNetworkImage(
14
          imageUrl: imageUrls[index],
15
          memCacheWidth: (150 * pixelRatio).round(),
16
          memCacheHeight: (150 * pixelRatio).round(),
17
          maxWidthDiskCache: 600,
18
          maxHeightDiskCache: 600,
19
          fit: BoxFit.cover,
20
          placeholder: (context, url) => Container(
21
            width: 150,
22
            height: 150,
23
            color: Colors.grey[300],
24
          ),
25
        );
26
      },
27
    );
28
  }
29
}

ResizeImage로 직접 크기 조절

1
Image(
2
  image: ResizeImage(
3
    const AssetImage('assets/images/large.jpg'),
4
    width: 200,
5
    height: 200,
6
  ),
7
  fit: BoxFit.cover,
8
)

Watch out#

WARNING
cacheWidth/cacheHeight는 논리적 픽셀 기준입니다.
실제 렌더링 품질을 위해서는 devicePixelRatio를 곱해야 합니다.
1
// 잘못된 방법 - 고밀도 화면에서 흐릿하게 보임
2
Image.asset(
3
  'assets/images/photo.jpg',
4
  width: 100,
5
  cacheWidth: 100,  // 3.0x 화면에서는 300px 영역에 100px 이미지
6
)
7

8
// 올바른 방법
9
Image.asset(
10
  'assets/images/photo.jpg',
11
  width: 100,
12
  cacheWidth: (100 * MediaQuery.devicePixelRatioOf(context)).round(),
13
)
디코딩 크기가 너무 작으면 이미지 품질이 저하됩니다. 표시 크기보다 약간 크게 설정하는 것이 좋습니다.

결론: cacheWidth/cacheHeight로 표시 크기에 맞게 이미지를 캐싱하면 메모리 사용량을 크게 줄일 수 있습니다.

한계#

Flutter의 에셋 시스템은 대부분의 상황을 처리하지만 몇 가지 제약이 있습니다.

SVG 미지원: 기본 Image 위젯은 SVG를 지원하지 않습니다. flutter_svg 패키지가 필요합니다.
HEIC/HEIF 제한: iOS의 HEIC 포맷은 직접 지원하지 않으며 플랫폼 변환이 필요합니다.
에셋 핫 리로드 제한: pubspec.yaml의 에셋 변경은 앱을 다시 실행해야 반영됩니다.
번들 크기: 모든 해상도 변형을 포함하면 앱 크기가 증가합니다.

Image.asset(): 앱 번들에 포함된 에셋 이미지를 로드하는 생성자다. ↩
Image.network(): URL에서 이미지를 다운로드해서 표시하는 생성자다. ↩
cached_network_image: 네트워크 이미지를 디스크와 메모리에 캐싱하는 Flutter 패키지다. ↩
pubspec.yaml: Flutter 프로젝트의 의존성, 에셋, 메타데이터를 정의하는 설정 파일이다. ↩
devicePixelRatio: 논리적 픽셀과 물리적 픽셀의 비율이다. 3.0x 화면은 논리적 1픽셀이 물리적 3×3픽셀이다. ↩
rootBundle: 앱 번들에 포함된 에셋에 접근하는 전역 AssetBundle 객체다. ↩

Flutter 튜토리얼 20편: 에셋과 이미지 처리

요약#

핵심 요지#

문서가 설명하는 범위#

참고 자료#

문제 상황#

에셋 관리의 어려움#

해결 방법#

챕터 1: pubspec.yaml에 에셋 등록하기#

Why#

What#

How#

Watch out#

챕터 2: 해상도별 이미지 변형 관리#

Why#

What#

How#

Watch out#

챕터 3: Image 위젯으로 이미지 표시#

Why#

What#

How#

Watch out#

챕터 4: 텍스트 에셋 로드#

Why#

What#

How#

Watch out#

챕터 5: 네트워크 이미지 캐싱#

Why#

What#

How#

Watch out#

챕터 6: 이미지 메모리 최적화#

Why#

What#

How#

Watch out#

한계#

Footnotes#

공유

목차