Flutter缓存与离线优先架构实现指南：数据同步、SQLite、图片优化

flutter-caching-data by flutter/skills

2,200 周安装量

822 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/flutter/skills --skill flutter-caching-data

开发

🇨🇳中文介绍

实现 Flutter 缓存与离线优先架构

选择缓存策略

根据数据生命周期和大小要求应用适当的缓存机制。

如果需要存储小型、非关键的 UI 状态或偏好设置： 使用 shared_preferences。
如果需要存储大型、结构化的数据集： 使用设备端数据库（通过 sqflite、Drift、Hive CE 或 Isar 使用 SQLite）。
如果需要存储二进制数据或大型媒体文件： 通过 path_provider 使用文件系统缓存。
如果需要保留用户会话状态（导航、滚动位置）： 实现 Flutter 内置的状态恢复功能，以同步 Element 树与引擎。
如果需要优化 Android 初始化： 预热并缓存 FlutterEngine。

实现离线优先数据同步

将数据仓库设计为单一数据源，结合本地数据库和远程 API 客户端。

读取操作（流式方法）

立即产出本地数据以实现快速 UI 渲染，然后获取远程数据，更新本地缓存，并产出新数据。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

管理文件系统和 SQLite 持久化

使用 path_provider 来定位正确的目录。

使用 getApplicationDocumentsDirectory() 获取持久化数据目录。
使用 getTemporaryDirectory() 获取操作系统可以清理的缓存数据目录。

Future<File> get _localFile async { final directory = await getApplicationDocumentsDirectory(); return File('${directory.path}/cache.txt'); }

使用 sqflite 进行关系型数据缓存。始终使用 whereArgs 来防止 SQL 注入。

Future<void> updateCachedRecord(Record record) async {
  final db = await database;
  await db.update(
    'records',
    record.toMap(),
    where: 'id = ?',
    whereArgs: [record.id], // 切勿在此处使用字符串插值
  );
}

优化 UI、滚动和图片缓存

图片 I/O 和解压缩开销很大。

使用 cached_network_image 包来处理远程图片的文件系统缓存。
自定义 ImageProviders： 如果实现自定义的 ImageProvider，请重写 createStream() 和 resolveStreamForKey() 方法，而不是已弃用的 resolve() 方法。
缓存大小调整： ImageCache.maxByteSize 不再为大型图片自动扩展。如果加载的图片大于默认缓存大小，请手动增加 ImageCache.maxByteSize 或子类化 ImageCache 以实现自定义的淘汰逻辑。

为可滚动小部件（ListView、GridView、Viewport）配置缓存时，请使用 scrollCacheExtent 属性配合 ScrollCacheExtent 对象。不要使用已弃用的 cacheExtent 和 cacheExtentStyle 属性。

// 正确实现
ListView(
  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
  children: // ...
)

Viewport(
  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
  slivers: // ...
)

避免在 Widget 对象上重写 operator ==。这会导致重建期间出现 O(N²) 行为。
例外情况： 您仅可以在叶子小部件（无子部件）上重写 operator ==，前提是比较属性的速度明显快于重建，并且属性很少更改。
优先使用 const 构造函数，以允许框架自动短路重建。

缓存 FlutterEngine (Android)

为了在将 Flutter 添加到现有 Android 应用时消除 FlutterEngine 不可忽视的预热时间，请预热并缓存引擎。

在 Application 类中实例化并预热引擎。
将其存储在 FlutterEngineCache 中。
在 FlutterActivity 或 FlutterFragment 中使用 withCachedEngine 检索它。

// 1. 在 Application 类中预热

val flutterEngine = FlutterEngine(this)
flutterEngine.navigationChannel.setInitialRoute("/cached_route")
flutterEngine.dartExecutor.executeDartEntrypoint(DartEntrypoint.createDefault())

// 2. 缓存引擎
FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)

// 3. 在 Activity/Fragment 中使用
startActivity(
  FlutterActivity.withCachedEngine("my_engine_id").build(this)
)

注意：使用缓存引擎时，无法通过 Activity/Fragment 构建器设置初始路由。在执行 Dart 入口点之前，在引擎的导航通道上设置初始路由。

工作流程：实现离线优先数据仓库

按照以下步骤实现健壮的离线优先数据层。

任务进度：
- 定义一个带有 synchronized 布尔标志（默认 false）的数据模型。
- 实现具有 CRUD 操作的本地 DatabaseService（SQLite/Hive）。
- 实现用于网络请求的远程 ApiClientService。
- 创建结合了两种服务的 Repository 类。
- 实现返回 Stream<T> 的读取方法（产出本地数据，获取远程数据，更新本地数据，产出远程数据）。
- 实现写入方法（写入本地数据，尝试远程调用，更新 synchronized 标志）。
- 实现后台同步函数来处理 synchronized == false 的记录。
- 运行验证器 -> 查看错误 -> 修复（通过禁用网络测试离线行为）。

工作流程：预热 Android FlutterEngine

按照以下步骤缓存 FlutterEngine 以实现无缝的 Android 集成。

任务进度：
- 定位 Android Application 类（如果不存在则创建一个，并在 AndroidManifest.xml 中注册）。
- 实例化一个新的 FlutterEngine。
- （可选）通过 navigationChannel.setInitialRoute() 设置初始路由。
- 通过 dartExecutor.executeDartEntrypoint() 执行 Dart 入口点。
- 将引擎存储在 FlutterEngineCache.getInstance().put() 中。
- 更新目标 FlutterActivity 或 FlutterFragment 以使用 .withCachedEngine("id")。
- 运行验证器 -> 查看错误 -> 修复（验证过渡期间没有出现空白屏幕）。

🇺🇸English

Implementing Flutter Caching and Offline-First Architectures

Selecting a Caching Strategy
Implementing Offline-First Data Synchronization
Managing File System and SQLite Persistence
Optimizing UI, Scroll, and Image Caching
Caching the FlutterEngine (Android)
Workflows

Selecting a Caching Strategy

Apply the appropriate caching mechanism based on the data lifecycle and size requirements.

If storing small, non-critical UI states or preferences: Use shared_preferences.
If storing large, structured datasets: Use on-device databases (SQLite via sqflite, Drift, Hive CE, or Isar).
If storing binary data or large media: Use file system caching via path_provider.
If retaining user session state (navigation, scroll positions): Implement Flutter's built-in state restoration to sync the Element tree with the engine.
If optimizing Android initialization: Pre-warm and cache the FlutterEngine.

Implementing Offline-First Data Synchronization

Design repositories as the single source of truth, combining local databases and remote API clients.

Read Operations (Stream Approach)

Yield local data immediately for fast UI rendering, then fetch remote data, update the local cache, and yield the fresh data.

Stream<UserProfile> getUserProfile() async* {
  // 1. Yield local cache first
  final localProfile = await _databaseService.fetchUserProfile();
  if (localProfile != null) yield localProfile;

  // 2. Fetch remote, update cache, yield fresh data
  try {
    final remoteProfile = await _apiClientService.getUserProfile();
    await _databaseService.updateUserProfile(remoteProfile);
    yield remoteProfile;
  } catch (e) {
    // Handle network failure; UI already has local data
  }
}

Write Operations

Determine the write strategy based on data criticality:

If strict server synchronization is required (Online-only): Attempt the API call first. Only update the local database if the API call succeeds.
If offline availability is prioritized (Offline-first): Write to the local database immediately. Attempt the API call. If the API call fails, flag the local record for background synchronization.

Background Synchronization

Add a synchronized boolean flag to your data models. Run a periodic background task (e.g., via workmanager or a Timer) to push unsynchronized local changes to the server.

Managing File System and SQLite Persistence

File System Caching

Use path_provider to locate the correct directory.

Use getApplicationDocumentsDirectory() for persistent data.
Use getTemporaryDirectory() for cache data the OS can clear.

Future<File> get _localFile async { final directory = await getApplicationDocumentsDirectory(); return File('${directory.path}/cache.txt'); }

SQLite Persistence

Use sqflite for relational data caching. Always use whereArgs to prevent SQL injection.

Future<void> updateCachedRecord(Record record) async {
  final db = await database;
  await db.update(
    'records',
    record.toMap(),
    where: 'id = ?',
    whereArgs: [record.id], // NEVER use string interpolation here
  );
}

Optimizing UI, Scroll, and Image Caching

Image Caching

Image I/O and decompression are expensive.

Use the cached_network_image package to handle file-system caching of remote images.
Custom ImageProviders: If implementing a custom ImageProvider, override createStream() and resolveStreamForKey() instead of the deprecated resolve() method.
Cache Sizing: The ImageCache.maxByteSize no longer automatically expands for large images. If loading images larger than the default cache size, manually increase ImageCache.maxByteSize or subclass ImageCache to implement custom eviction logic.

Scroll Caching

When configuring caching for scrollable widgets (ListView, GridView, Viewport), use the scrollCacheExtent property with a ScrollCacheExtent object. Do not use the deprecated cacheExtent and cacheExtentStyle properties.

// Correct implementation
ListView(
  scrollCacheExtent: const ScrollCacheExtent.pixels(500.0),
  children: // ...
)

Viewport(
  scrollCacheExtent: const ScrollCacheExtent.viewport(0.5),
  slivers: // ...
)

Widget Caching

Avoid overriding operator == on Widget objects. It causes O(N²) behavior during rebuilds.
Exception: You may override operator == only on leaf widgets (no children) where comparing properties is significantly faster than rebuilding, and the properties rarely change.
Prefer using const constructors to allow the framework to short-circuit rebuilds automatically.

Caching the FlutterEngine (Android)

To eliminate the non-trivial warm-up time of a FlutterEngine when adding Flutter to an existing Android app, pre-warm and cache the engine.

Instantiate and pre-warm the engine in the Application class.
Store it in the FlutterEngineCache.
Retrieve it using withCachedEngine in the FlutterActivity or FlutterFragment.

// 1. Pre-warm in Application class

val flutterEngine = FlutterEngine(this)
flutterEngine.navigationChannel.setInitialRoute("/cached_route")
flutterEngine.dartExecutor.executeDartEntrypoint(DartEntrypoint.createDefault())

// 2. Cache the engine
FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine)

// 3. Use in Activity/Fragment
startActivity(
  FlutterActivity.withCachedEngine("my_engine_id").build(this)
)

Note: You cannot set an initial route via the Activity/Fragment builder when using a cached engine. Set the initial route on the engine's navigation channel before executing the Dart entrypoint.

Workflows

Workflow: Implementing an Offline-First Repository

Follow these steps to implement a robust offline-first data layer.

Task Progress:
- Define the data model with a synchronized boolean flag (default false).
- Implement the local DatabaseService (SQLite/Hive) with CRUD operations.
- Implement the remote ApiClientService for network requests.
- Create the Repository class combining both services.
- Implement the read method returning a Stream<T> (yield local, fetch remote, update local, yield remote).
- Implement the write method (write local, attempt remote, update synchronized flag).
- Implement a background sync function to process records where synchronized == false.
- Run validator -> review errors -> fix (Test offline behavior by disabling network).

Workflow: Pre-warming the Android FlutterEngine

Follow these steps to cache the FlutterEngine for seamless Android integration.

Task Progress:
- Locate the Android Application class (create one if it doesn't exist and register in AndroidManifest.xml).
- Instantiate a new FlutterEngine.
- (Optional) Set the initial route via navigationChannel.setInitialRoute().
- Execute the Dart entrypoint via dartExecutor.executeDartEntrypoint().
- Store the engine in FlutterEngineCache.getInstance().put().
- Update the target FlutterActivity or FlutterFragment to use .withCachedEngine("id").

Weekly Installs

1.8K

Repository

flutter/skills

GitHub Stars

784

First Seen

11 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex1.8K

gemini-cli1.8K

opencode1.8K

github-copilot1.8K

kimi-cli1.8K

cursor1.8K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Run validator -> review errors -> fix (Verify no blank screen appears during transition).