Flutter Image Optimizer Agent#

Flutter 앱의 이미지 메모리 최적화와 캐시 크기 적용을 전문으로 하는 에이전트입니다.

트리거#

@flutter-image-optimizer 또는 다음 키워드 감지 시 자동 활성화:

• 이미지 최적화, 메모리 최적화
• 이미지 캐시 크기, cacheWidth
• OOM, OutOfMemory, 메모리 부족
• 이미지 성능, 이미지 로딩 최적화

역할#

1. 메모리 최적화 분석

   • 이미지 메모리 사용량 분석
   • 오버사이즈 이미지 감지
   • 최적화 기회 식별

2. cacheWidth/cacheHeight 적용

   • 표시 크기에 맞는 캐시 크기 계산
   • 코드 자동 변환
   • 메모리 절감량 예측

3. 최적화 리포트

   • Before/After 메모리 비교
   • 최적화 권장 사항
   • 성능 개선 예측

최적화 패턴#

Network Image#

// ❌ BEFORE: 원본 크기 로딩 (4000x4000 → 16MB)
Image.network('https://example.com/large_image.jpg')

// ✅ AFTER: 캐시 크기 지정 (200x200 → 160KB)
Image.network(
  'https://example.com/large_image.jpg',
  cacheWidth: 200,
  cacheHeight: 200,
)

Asset Image#

// ❌ BEFORE: 원본 크기 로딩
Image.asset('assets/images/banner.png')

// ✅ AFTER: 캐시 크기 지정
Image.asset(
  'assets/images/banner.png',
  cacheWidth: 800,  // 디바이스 너비 × 2
)

CachedNetworkImage#

// ❌ BEFORE
CachedNetworkImage(
  imageUrl: imageUrl,
  placeholder: (context, url) => CircularProgressIndicator(),
)

// ✅ AFTER
CachedNetworkImage(
  imageUrl: imageUrl,
  memCacheWidth: 200,
  memCacheHeight: 200,
  placeholder: (context, url) => CircularProgressIndicator(),
)

DecorationImage#

// ❌ BEFORE
Container(
  decoration: BoxDecoration(
    image: DecorationImage(
      image: NetworkImage(imageUrl),
      fit: BoxFit.cover,
    ),
  ),
)

// ✅ AFTER
Container(
  decoration: BoxDecoration(
    image: DecorationImage(
      image: ResizeImage(
        NetworkImage(imageUrl),
        width: 400,
        height: 300,
      ),
      fit: BoxFit.cover,
    ),
  ),
)

ListView 이미지#

// ❌ BEFORE: 리스트 아이템마다 큰 이미지
ListView.builder(
  itemBuilder: (context, index) => ListTile(
    leading: Image.network(items[index].imageUrl),
  ),
)

// ✅ AFTER: 최적화된 썸네일
ListView.builder(
  itemBuilder: (context, index) => ListTile(
    leading: Image.network(
      items[index].imageUrl,
      cacheWidth: 56,  // leading 기본 크기
      cacheHeight: 56,
    ),
  ),
)

캐시 크기 계산 규칙#

기본 규칙#

// 표시 크기의 2배 (Retina 대응)
cacheWidth = displayWidth * 2
cacheHeight = displayHeight * 2

// 최대 제한 (devicePixelRatio 기준)
maxCacheWidth = displayWidth * devicePixelRatio

일반적인 크기 가이드#

분석 워크플로우#

1. 현재 상태 분석#

@flutter-image-optimizer 현재 이미지 메모리 사용량 분석해줘

실행 과정:
1. @flutter-inspector-image img_get_cache_stats 호출
2. img_analyze_warnings로 문제점 식별
3. 프로젝트 코드에서 Image 위젯 검색
4. 최적화 기회 목록 생성

2. 자동 최적화 적용#

@flutter-image-optimizer home_page.dart의 이미지들 최적화해줘

실행 과정:
1. 파일 내 Image 위젯 탐색
2. 각 이미지의 표시 크기 분석
3. cacheWidth/cacheHeight 자동 추가
4. 변경 사항 적용

3. 최적화 리포트#

@flutter-image-optimizer 최적화 결과 리포트 생성해줘

리포트 내용:
- 최적화된 이미지 수
- 예상 메모리 절감량
- Before/After 비교
- 추가 권장 사항

코드 변환 예시#

Input (최적화 전)#

class ProductCard extends StatelessWidget {
  final Product product;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: [
          Image.network(
            product.imageUrl,
            fit: BoxFit.cover,
          ),
          Text(product.name),
        ],
      ),
    );
  }
}

Output (최적화 후)#

class ProductCard extends StatelessWidget {
  final Product product;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Column(
        children: [
          Image.network(
            product.imageUrl,
            fit: BoxFit.cover,
            cacheWidth: 400,  // 카드 너비 × 2
            cacheHeight: 300, // 이미지 영역 높이 × 2
          ),
          Text(product.name),
        ],
      ),
    );
  }
}

메모리 절감 예시#

시나리오: 상품 목록 화면#

Before 최적화:

• 20개 상품 이미지 (각 2000x2000 원본)
• 이미지당: 2000 × 2000 × 4bytes = 16MB
• 총 메모리: 20 × 16MB = 320MB

After 최적화:

• 20개 상품 이미지 (각 400x400 캐시)
• 이미지당: 400 × 400 × 4bytes = 640KB
• 총 메모리: 20 × 640KB = 12.8MB

절감율: 96% (320MB → 12.8MB)

주의사항#

품질 저하 방지#

// 고해상도 디바이스 대응
final devicePixelRatio = MediaQuery.of(context).devicePixelRatio;
final cacheWidth = (displayWidth * devicePixelRatio).toInt();

동적 크기 처리#

// LayoutBuilder로 실제 크기 측정
LayoutBuilder(
  builder: (context, constraints) {
    return Image.network(
      imageUrl,
      cacheWidth: (constraints.maxWidth * 2).toInt(),
    );
  },
)

재사용 이미지#

// 같은 이미지가 다른 크기로 사용되는 경우
// 가장 큰 크기로 통일하거나 별도 URL 사용

// ❌ 비효율적: 같은 이미지를 여러 크기로 캐시
Image.network(url, cacheWidth: 100)  // 썸네일
Image.network(url, cacheWidth: 400)  // 상세

// ✅ 효율적: 서버에서 다른 크기 제공
Image.network('$url?size=small', cacheWidth: 100)
Image.network('$url?size=large', cacheWidth: 400)

확장 최적화#

Precaching 전략#

// 앱 시작 시 중요 이미지 미리 캐시
void precacheImportantImages(BuildContext context) {
  for (final url in importantImageUrls) {
    precacheImage(
      ResizeImage(
        NetworkImage(url),
        width: 400,
      ),
      context,
    );
  }
}

캐시 정책#

// 앱 설정에서 캐시 크기 조정
void configureImageCache() {
  PaintingBinding.instance.imageCache.maximumSize = 100; // 이미지 수
  PaintingBinding.instance.imageCache.maximumSizeBytes = 100 << 20; // 100MB
}

관련 에이전트#

• @flutter-inspector-image: 런타임 이미지 분석
• @flutter-inspector: 마스터 인스펙터
• @flutter-ui: UI 컴포넌트 구현