Deep Dive into Flutter's Image.network Source Code and Caching Mechanism

The article begins by introducing the need for efficient image handling in Flutter, noting that as mobile hardware advances, developers must manage memory and caching when displaying images, and mentions popular Android image libraries before focusing on Flutter's Image widget.

It explains that Image is a StatefulWidget with several constructors (e.g., Image.network , Image.asset , Image.file ) and lists its key properties such as width , height , fit , color , and others.

The internal class hierarchy is described, including Image , _ImageState , ImageProvider , NetworkImage , ImageStream , ImageStreamCompleter , and MultiFrameImageStreamCompleter . The article walks through the lifecycle: ImageState calls _resolveImage , which creates an ImageStream and invokes ImageProvider.resolve to obtain a key and set up an ImageStreamCompleter .

The default caching behavior is examined via PaintingBinding.instance.imageCache.putIfAbsent , showing how images are stored with a maximum count of 1000 and a size limit of 10 MiB, and how the cache updates when a new image is loaded.

For network images, the NetworkImage.load method is detailed. It resolves the URL, performs an HTTP GET request, validates the response, reads the bytes, and creates a ui.Codec using instantiateImageCodec . This codec is then wrapped in a MultiFrameImageStreamCompleter , which handles both static and animated images.

The article explains how MultiFrameImageStreamCompleter fetches frames via codec.getNextFrame() , emits them with _emitFrame , and schedules subsequent frames for animated images using SchedulerBinding.instance.scheduleFrameCallback . For static images, it directly creates an ImageInfo and calls setImage .

Finally, the _ImageState.build method builds a RawImage widget using the latest ImageInfo and the original widget properties, rendering the image on screen.

The conclusion summarizes the entire flow, highlighting the entry points, caching strategy, and how developers can extend or replace the default caching mechanism for custom image frameworks.