CachedNetworkImage(커뮤니티 에디션)용 플랫폼 인터페이스 패키지로, 크로스플랫폼 이미지 로딩과 캐싱 지원을 가능하게 합니다. Android, iOS, Linux, macOS, Windows에서 메모리 및 디스크 캐시를 효율적으로 관리하면서 네트워크 이미지를 가져오고 표시하기 위한 표준화된 API를 제공합니다. 이 인터페이스는 핵심 구현을 수정하지 않고도 이미지 로딩 동작을 확장하거나 사용자 정의할 수 있도록 해줍니다. 커뮤니티 에디션의 캐시된 네트워크 이미지 기능과 통합이 필요한 플러그인 또는 패키지에서 사용하도록 설계되었습니다.
사용 사례
URL에서 이미지를 로드하고 자동 캐싱
이미지가 많은 앱에서 여러 플랫폼 지원
사용자 지정 이미지 로딩 로직 활성화
제3자 이미지 처리 플러그인과의 통합
이미지 표시를 사용하여 재사용 가능한 UI 컴포넌트 만들기
주요 기능
크로스 플랫폼 호환성
효율적인 디스크 및 메모리 캐싱
확장 가능한 플랫폼 인터페이스
이미지 플레이스홀더 및 오류 처리를 지원
경량이고 모듈러한 디자인
적합한 대상
다중 플랫폼 Flutter 앱을 개발하는 개발자
사용자 정의 이미지 로딩 솔루션을 유지 관리하는 팀
일관된 이미지 가져오기 동작을 요구하는 플러그인
최적화된 이미지 성능이 필요한 앱
이미지 기능을 확장하는 오픈소스 기여자
고려 사항
주요 cached_network_image_ce 패키지와의 통합이 필요합니다
커뮤니티 에디션 생태계 내에서만 사용 가능
사용자 지정 플랫폼 구현을 위해 추가 설정이 필요할 수 있습니다
앱 코드에서 직접 사용하기 위한 것이 아님
하위 플랫폼 전용 구현에 의존합니다
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
Zero-jank image caching for Flutter
cached_network_image_ce is the actively maintained fork of
cached_network_image,
rebuilt around a caching engine that doesn't block your UI thread. Same widget and provider API you already use.
cached_network_image by Baseflow is one of the most widely used packages in the Flutter ecosystem. It has also been effectively unmaintained since August 2024, sitting on 300+ open issues, including memory leaks and scroll-performance bugs that never got fixed.
Under the hood it leans on sqflite for cache metadata: a full SQL engine routed through a platform channel just to answer "have I already downloaded this image?" On image-heavy lists, that overhead shows up as jank you can feel.
We didn't fork this just to merge dependabot PRs. We rebuilt the caching layer.
We swapped sqflite for hive_ce, a pure-Dart, non-blocking key-value store. It skips the platform channel round trip and the SQL parser entirely, so there's no jank left to fix.
How we stack up
vs. the original cached_network_image:
Original (cached_network_image)
This fork (cached_network_image_ce)
Cache backend
sqflite (platform channel)
✅ hive_ce (pure Dart)
Maintenance
❌ stale since Aug 2024
✅ active, regular releases
Web caching
⚠️ browser cache only
✅ full persistent IndexedDB cache
HTTP / cache interceptors
❌
✅ full chains (auth, logging, custom responses)
Cache eviction
❌ fixed
✅ pluggable — TTL or LRU
Cache read (10 KB)
16 ms
✅ 2 ms — 8x faster
Unsupported formats (SVG/AVIF/HEIC)
❌ opaque decode error
✅ unsupportedImageBuilder hook
vs. other popular alternatives, checked live against pub.dev, so this is current rather than a guess:
Package
Cache backend
Web support
Interceptors
Cleanup strategy
Maintenance
cached_network_image_ce (this)
hive_ce
✅ full IndexedDB
✅ HTTP + cache
✅ TTL / LRU
✅ active
cached_network_image
sqflite
⚠️ browser only
❌
❌ fixed
❌ stale
flutter_cache_manager
sqflite / plain JSON
✅
❌
❌ fixed
✅ active
extended_image
undisclosed
✅
⚠️ headers/retry only
⚠️ manual clear
✅ active
fast_cached_network_image
hive (plain)
✅ (claimed)
❌
⚠️ TTL only
⚠️ stale (17mo)
Worth saying plainly: flutter_cache_manager and extended_image are both actively maintained by reputable teams. They're solving different problems than we are: a generic file cache, and a broad image/gesture toolkit, respectively. The "actively maintained fork" pitch applies specifically against the original cached_network_image, which this package is a drop-in replacement for.
Architecture
flowchart LR
W[CachedNetworkImage widget] --> P[CachedNetworkImageProvider]
P --> M[DefaultCacheManager]
M --> H[("Hive CE<br/>metadata: URL, path,<br/>validTill, eTag")]
M --> FS[("Native filesystem<br/>raw image bytes")]
H -.cache hit.-> P
FS -.cache hit.-> P
subgraph Original[Original package, for comparison]
direction LR
W2[CachedNetworkImage] --> M2[CacheManager]
M2 --> PC[Platform Channel]
PC --> SQL[(SQLite via sqflite)]
end
The quick start above covers the basics. For interceptors, cleanup strategies, connection timeouts, custom cache and metadata directories, web render modes, and unsupported-format handling, see the full reference:
Q: Will I lose my users' existing cache if I migrate?
A: Yes. Because we switched the storage engine from SQLite to Hive, the old cache files will be ignored. Users will re-download images once as they browse. This is a one-time migration cost for a permanent performance gain.
Q: My app crashes/pauses on errors?
A: In Debug mode, Flutter may pause on exceptions even if they are caught. This is expected behavior for network errors (404s). In Release mode, these are handled silently by the errorWidget.
Q: Why is web caching slower, or why does it use Hive for image bytes?
A: On Mobile & Desktop (IO), this package stores image bytes directly on the native file system and uses Hive only for metadata. Web lacks a native file system, so hive_ce stores both metadata and image bytes in IndexedDB there. Serializing large byte arrays in and out of IndexedDB carries overhead that doesn't exist on IO.
Alternative: if persistent caching across sessions isn't critical for your web users, consider conditionally using Image.network on web, which relies on the browser's built-in caching.
Contributing
We welcome contributions! If you want to help maintain this package, check CONTRIBUTING.md.