[Flutter] CachedNetworkImage 캐시 초기화 / 수동 리프레시 방법

[Flutter] CachedNetworkImage 캐시 초기화 / 수동 리프레시 방법

CachedNetworkImage는 네트워크 이미지를 로컬에 저장(캐시)해두고 다음에 같은 URL을 불러오면 빠르게 보여주는 Flutter 이미지 최적화 패키지입니다.

하지만 가끔은 이미지 캐시를 초기화하거나 강제로 새로고침(refresh)하고 싶을 때가 있습니다.
이 글에서는 실무에서 자주 사용하는 캐시 초기화 & 수동 리프레시 방법을 소개합니다.

---

✅ 1. 캐시 전체 초기화 (비우기)

전체 이미지 캐시를 비우고 싶을 땐 DefaultCacheManager의 emptyCache()를 사용합니다.

import 'package:flutter_cache_manager/flutter_cache_manager.dart';

await DefaultCacheManager().emptyCache();

→ 이 메서드는 모든 캐시된 이미지 파일을 삭제합니다.
앱 설정 초기화, 로그아웃 시 함께 사용하면 좋습니다.

---

✅ 2. 특정 URL 캐시 삭제

await DefaultCacheManager().removeFile('https://example.com/image.jpg');

→ 특정 이미지만 새로 받아야 할 때 유용합니다.
예: 사용자가 프로필 사진을 바꿨을 때

---

✅ 3. 수동 리프레시 구현 (버튼 클릭 시 이미지 다시 로드)

String imageUrl = 'https://example.com/profile.jpg';
int version = 0;

CachedNetworkImage(
  key: ValueKey(version),
  imageUrl: '$imageUrl?v=$version', // 버전 파라미터로 강제 갱신
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
),

// 버튼 클릭 시 버전 증가
ElevatedButton(
  onPressed: () {
    setState(() {
      version++;
    });
  },
  child: Text("이미지 새로고침"),
)

→ 쿼리 파라미터나 key 변경으로 CachedNetworkImage가 새로 로드되도록 유도할 수 있습니다.

---

✅ 4. 커스텀 CacheManager로 유효기간 설정하기

class CustomCacheManager extends CacheManager {
  static const key = "customCache";

  CustomCacheManager() : super(
    Config(
      key,
      stalePeriod: const Duration(hours: 6), // 6시간 후 자동 새로고침
      maxNrOfCacheObjects: 100,
    ),
  );
}

CachedNetworkImage(
  imageUrl: 'https://example.com/image.jpg',
  cacheManager: CustomCacheManager(),
)

→ stalePeriod를 설정하면 자동으로 갱신 주기를 관리할 수 있습니다.

---

📌 마무리

CachedNetworkImage는 이미지 최적화에 탁월하지만, 수동 캐시 제어 기능까지 함께 익혀두면 앱 사용자 경험(UX)을 훨씬 더 매끄럽게 만들 수 있습니다.

이미지 변경이 자주 발생하는 앱이라면 버전 파라미터 + 캐시 삭제 + 커스텀 CacheManager 조합을 적극 활용해보세요!

도움이 되셨다면 공감 / 댓글 부탁드립니다 😊