一個用於 CachedNetworkImage(社群版)的平台介面套件,支援跨平台影像載入並具備快取功能。它提供一套標準化的 API,用於取得與顯示網路影像,同時在 Android、iOS、Linux、macOS 與 Windows 上有效管理記憶體與磁碟快取。此介面允許開發者在不修改核心實作的情況下擴充或自訂影像載入行為。此介面專為需要與快取網路影像社群版功能整合的外掛或套件所設計。
適用情境
從URL加載圖像並自動快取
在圖像密集型應用中支援多種平台
啟用自定義圖像載入邏輯
與第三方圖像處理外掛程式整合
使用圖像顯示建構可重用的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.