【Flutter踩坑排雷】第12课：图片内存坑｜大图无约束加载，OOM内存溢出排查修复

摘要：本文聚焦 Flutter 图片内存问题，指出图片内存由「解码尺寸 × 存活数量」决定，而非磁盘文件大小——一张 2MB 的 JPEG 解码后可能占用 48MB。文章先剖析四种“无约束解码”姿态（文件大小与解码内存脱钩、cacheWidth/cacheHeight 的物理像素陷阱、ImageCache 的 live 例外、动画图片尺寸参数失效），再从解码放大、参数作用点、LRU 边界、懒构建语义四个层面深挖根因；随后归纳四类经典故障模式，给出“先算、再看、后改”的系统性排查五步法，并按解码尺寸与存活数量两个维度提出六层修复方案与六条预防原则，最后配 15 道课后习题巩固。

目录

• 前言
• 一、故障现场：图片内存的四种“无约束解码”
  • 姿态一：2MB 的 JPEG，48MB 的 RAM——“文件大小”与“解码内存”的彻底脱钩
  • 姿态二：cacheWidth/cacheHeight 的“物理像素陷阱”——给了参数，却给了错误的单位
  • 姿态三：ImageCache 的“live 例外”——缓存有限，但正在显示的大图可以绕过上限
  • 姿态四：动画图片的“尺寸参数无效”——cacheWidth 对 GIF/WebP/APNG 不生效
• 二、根因剖析：图片内存由“解码尺寸 × 存活数量”决定，而这两者都不受直觉控制
  • 2.1 解码是内存的“放大器”：压缩字节 → 未压缩像素
  • 2.2 cacheWidth/cacheHeight 的作用点在解码器，不在布局引擎
  • 2.3 ImageCache 的 LRU 只约束“缓存”，不约束“存活”
  • 2.4 ListView 的“懒构建”不自动等于“内存释放”
• 三、经典故障模式与深入案例
  • 模式一：12MP 头像的 48MB 解码——布局尺寸不约束解码尺寸
  • 模式二：动画贴纸网格的 OOM——cacheWidth 静默失效
  • 模式三：precacheImage 的“好心办坏事”——预加载把大图钉在内存中
  • 模式四：ImageCache 的“驱逐抖动”——大图无法进入缓存，每次滚动都重新解码
• 四、系统性排查方法论
  • 第一步：先计算“理论解码内存”，而不是猜测
  • 第二步：在 DevTools 的 Memory 视图中区分“图片内存”与“其他内存”
  • 第三步：检查每一张 Image 的 cacheWidth/cacheHeight 是否与布局尺寸和 DPR 匹配
  • 第四步：识别动画图片并确认尺寸参数是否有效
  • 第五步：区分“泄漏”与“缓存”与“live 钉住”
• 五、修复方案：按“解码尺寸”和“存活数量”两个维度分层
  • 第一层：对静态图片，用 cacheWidth/cacheHeight 将解码尺寸限制到显示尺寸
  • 第二层：对 ImageProvider 组合场景，用 ResizeImage 包裹
  • 第三层：对 ListView/GridView 中的图片，控制 cacheExtent 和 keepAlive
  • 第四层：对 precacheImage 建立“仅限关键小图”的纪律
  • 第五层：对动画图片，从“解码尺寸约束”转向“源尺寸约束”
  • 第六层：必要时调整 ImageCache 的预算，但不要把调大当作修复
• 六、预防体系：让“解码尺寸”成为图片加载的默认审查项
  • 原则一：每一张 Image 都必须回答“解码尺寸是多少”
  • 原则二：区分“布局尺寸”和“解码尺寸”，并确保换算正确
  • 原则三：对动画图片建立独立的资源规范
  • 原则四：把 precacheImage 当作“稀缺资源”而不是“通用优化”
  • 原则五：在 CI 或测试中监控图片解码内存的“理论峰值”
  • 原则六：在真机、低端设备和 Profile 模式下验证
• 七、课后习题（15道）
• 八、本节课知识要点总结
• 九、下节课预告—

前言

Flutter 应用里最容易被低估的内存杀手，往往不是某个复杂的状态管理方案，也不是某个没关掉的定时器，而是一张看起来“只有几百 KB”的图片。它安静地躺在 Image.network(url) 里，代码 review 时没人会多看一眼，直到某天用户在低端机上滑到列表的某个位置，应用毫无征兆地闪退——日志里只有一行 OutOfMemoryError。

这个坑的迷惑性在于：它违背了大多数开发者对“内存占用”的直觉。文件大小、布局尺寸、解码尺寸，这三个概念在日常开发中被混为一谈，而 Flutter 的图片管线恰恰把它们分得很清楚——width: 48 管的是画多大，cacheWidth: 144 管的才是解码多大，真正吃掉内存的是后者，前者对此毫无约束力。更麻烦的是，ImageCache 的 100MB 上限看起来像一道保险，但 live 引用可以合法地绕过它；cacheWidth 看起来像万能解药，但对 GIF/WebP/APNG 静默失效。

本文要做的，是把这条从“压缩字节”到“未压缩像素”的链路彻底拆开：先看四种典型的“无约束解码”现场，再从解码放大、参数作用点、LRU 边界、懒构建语义四个层面挖到根因；然后用四类经典故障模式把理论落到具体场景，给出“先算、再看、后改”的五步排查法；最后按“解码尺寸”和“存活数量”两个维度，给出六层修复方案与六条预防原则，并配 15 道习题帮你把认知固化下来。

读完之后，希望你在写下每一个 Image 时，都会下意识地问一句：这张图，解码尺寸是多少？

一、故障现场：图片内存的四种“无约束解码”

前十一课的故障大多可以从代码结构或调用方式中追溯：一个互斥的约束、一个不该写的 !、一个阻断重建的 const、一个溢出的 Positioned、一个全量实例化的 children 列表。图片内存问题的特殊性在于：磁盘上的文件大小与内存中的实际占用之间，几乎没有任何直观关系。一张 2MB 的 JPEG 可以轻松占用 48MB 的 RAM，而开发者看到 Image.network(url) 时，心智模型里往往只有“下载一张图片”，而不是“解压一个 4000×3000 的像素矩阵”。

姿态一：2MB 的 JPEG，48MB 的 RAM——“文件大小”与“解码内存”的彻底脱钩

Flutter 官方 Image 类的文档对此的表述是精确的：“图片以未压缩形式存储在内存中（以便渲染）。大图会占用大量内存：一张 4K 图片（3840×2160）会占用超过 30MB 的 RAM（假设每像素 32 位）”。Android 开发者文档给出的计算公式是同一件事的另一种表述：“Memory (Bytes) = Width × Height × Bytes Per Pixel”，并给出了一个具体的数字：“对于 4000×3000 像素的全分辨率照片，ARGB_8888 格式会占用 48MB”。

这意味着：一张 4000×3000 的 JPEG 在磁盘上可能只有 2MB，但解码为 RGBA_8888 位图后占用约 48MB——文件压缩率越高，磁盘大小与解码内存之间的差距就越大。一个开发者在一个聊天列表的 12MP 头像上踩坑时，他看到的可能只是一张“几百 KB 的头像”，但每次解码都在申请 48MB 的连续内存。如果页面上同时有几张这样的图片存活，或者它们被加载到一个不释放的列表中，OOM 会在用户滑动到某个位置时突然发生。

更关键的是，这 48MB 是解码后的像素数据，它不包含编码字节、解码器缓冲区、GPU 纹理开销和 Flutter ImageCache 的管理成本。buoy 包的 decodedPixelBytes 文档明确区分了这一点：“Estimated RGBA pixel storage, excluding Flutter’s global image cache, encoded bytes, retained pictures, decoder buffers and GPU overhead”。真实的峰值内存会高于这个估算值，而不是低于它。

姿态二：cacheWidth/cacheHeight 的“物理像素陷阱”——给了参数，却给了错误的单位

cacheWidth 和 cacheHeight 是 Flutter 为“限制解码尺寸”提供的直接手段。Image 文档的示例展示了它的威力：“一张 4K 图片如果只渲染到 384×216 像素（水平和垂直维度各十分之一），在指定这两个参数后只占用 330KB，内存减少约 100 倍”。instantiateImageCodecFromBuffer 的 API 文档进一步说明了语义：这两个参数“指示解码图片的目标尺寸”，当只指定其中一个时，“省略的维度将按原始宽高比缩放”，而当两者都省略时，“图片将按其原生分辨率解码”。

问题出在单位的混淆上。Image.network(url, width: 200) 中的 width: 200 是布局尺寸，逻辑像素；cacheWidth: 400 中的 400 是解码尺寸，物理像素。一个开发者如果看到设计稿上的图片宽度是 200，就写成 cacheWidth: 200，在 devicePixelRatio 为 2 或 3 的屏幕上，解码出的图片只有实际需要像素的一半或三分之一，视觉上表现为模糊；如果反过来，把源图的宽度直接传给 cacheWidth（例如 cacheWidth: 4000），则完全没有起到限制内存的作用。正确的换算方式是 cacheWidth = 逻辑宽度 × devicePixelRatio，正如一篇图片管线文章所总结的：“width: 200 是布局——逻辑像素。cacheWidth: 400 是解码——物理像素，所以大致是逻辑宽度乘以设备像素比。把逻辑宽度传给 cacheWidth 会在 2x 或 3x 屏幕上产生模糊图片；传源图宽度则违背了初衷”。

这个姿态的教学价值在于：cacheWidth 不是“一个可以随手填的数字”，它是一个需要与布局尺寸和设备密度精确协商的物理像素值。填错了，要么模糊，要么无效。

姿态三：ImageCache 的“live 例外”——缓存有限，但正在显示的大图可以绕过上限

Flutter 的 ImageCache 是一个最近最少使用（LRU） 的内存缓存，默认上限是 1000 张图片和 100MB。开发者通常会把“100MB”理解为“所有图片内存的总上限”，但 ImageCache 的机制中有一个关键的例外：live 引用。

ImageCache 的类文档描述：“缓存还持有一个 ‘live’ 引用列表。一张图片被认为是 live 的，如果它的 ImageStreamCompleter 的监听者数量在添加至少一个监听者之后从未降到零”。putIfAbsent 的文档补充了更重要的约束：“大于 maximumSizeBytes 的图片不会被缓存，也不会导致缓存中的其他图片被驱逐”。结合 precacheImage 的文档可以看清完整的图景：一张被 precacheImage 或正在被 Image Widget 监听的图片，“至少会保持在内存中，直到调用者从流中移除它的监听者，即使它本来不适合缓存”；文档同时警告：“调用者应谨慎将大图或大量图片钉在内存中，因为这可能导致内存耗尽并被操作系统杀死”。

这意味着：100MB 的 LRU 上限管的是“缓存中的图片”，不管“正在被监听或钉住的图片” 。如果页面上同时有 5 张 48MB 的大图处于 live 状态（例如一个横向 PageView 中相邻的几页，或者一个 GridView 的可见区域），它们可以合法地绕过 LRU 的上限，合计占用 240MB，而 ImageCache 的“100MB”这个数字对它们毫无约束力。

姿态四：动画图片的“尺寸参数无效”——cacheWidth 对 GIF/WebP/APNG 不生效

这是姿态二中“参数给了但没起作用”的一个更隐蔽的变体，而且它恰好发生在内存压力最大的场景中。Flutter 引擎的一个 PR 对此的表述是直接的：“cacheWidth/cacheHeight 和 ResizeImage 对动画 GIF、WebP 和 APNG 图片没有效果，这是高内存占用的一个常见来源（例如动画贴纸的网格）”。中文技术社区对 MOO 音乐项目的总结也指向同一类问题：“很多列表都使用 GIF 动图，大小可以达几 MB 乃至十几 MB，图片所占内存跟图片大小有关，影响更大的是图片缓存尺寸导致的内存增长，一旦出问题就很容易导致 OOM”。

这个姿态的危险在于：开发者以为已经做了优化。代码中写上了 cacheWidth: 400，analyzer 不会警告，代码 review 也不会发现问题，但动画图片的解码仍然按原始尺寸进行。一个由几十张动画贴纸组成的网格，每张贴纸的原始尺寸可能是 500×500 甚至更大，解码后的内存占用与静态大图在同一个量级，而尺寸限制参数在这个场景中是静默失效的。

二、根因剖析：图片内存由“解码尺寸 × 存活数量”决定，而这两者都不受直觉控制

先看一张图片从请求到渲染的完整管线图，理解内存问题发生在哪个阶段：

#mermaid-svg-BvSJ2ro7Tnu85FAz{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-BvSJ2ro7Tnu85FAz .error-icon{fill:#552222;}#mermaid-svg-BvSJ2ro7Tnu85FAz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-BvSJ2ro7Tnu85FAz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .marker.cross{stroke:#333333;}#mermaid-svg-BvSJ2ro7Tnu85FAz svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-BvSJ2ro7Tnu85FAz p{margin:0;}#mermaid-svg-BvSJ2ro7Tnu85FAz .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster-label text{fill:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster-label span{color:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster-label span p{background-color:transparent;}#mermaid-svg-BvSJ2ro7Tnu85FAz .label text,#mermaid-svg-BvSJ2ro7Tnu85FAz span{fill:#333;color:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .node rect,#mermaid-svg-BvSJ2ro7Tnu85FAz .node circle,#mermaid-svg-BvSJ2ro7Tnu85FAz .node ellipse,#mermaid-svg-BvSJ2ro7Tnu85FAz .node polygon,#mermaid-svg-BvSJ2ro7Tnu85FAz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .rough-node .label text,#mermaid-svg-BvSJ2ro7Tnu85FAz .node .label text,#mermaid-svg-BvSJ2ro7Tnu85FAz .image-shape .label,#mermaid-svg-BvSJ2ro7Tnu85FAz .icon-shape .label{text-anchor:middle;}#mermaid-svg-BvSJ2ro7Tnu85FAz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .rough-node .label,#mermaid-svg-BvSJ2ro7Tnu85FAz .node .label,#mermaid-svg-BvSJ2ro7Tnu85FAz .image-shape .label,#mermaid-svg-BvSJ2ro7Tnu85FAz .icon-shape .label{text-align:center;}#mermaid-svg-BvSJ2ro7Tnu85FAz .node.clickable{cursor:pointer;}#mermaid-svg-BvSJ2ro7Tnu85FAz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .arrowheadPath{fill:#333333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BvSJ2ro7Tnu85FAz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-BvSJ2ro7Tnu85FAz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BvSJ2ro7Tnu85FAz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster text{fill:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz .cluster span{color:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-BvSJ2ro7Tnu85FAz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-BvSJ2ro7Tnu85FAz rect.text{fill:none;stroke-width:0;}#mermaid-svg-BvSJ2ro7Tnu85FAz .icon-shape,#mermaid-svg-BvSJ2ro7Tnu85FAz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-BvSJ2ro7Tnu85FAz .icon-shape p,#mermaid-svg-BvSJ2ro7Tnu85FAz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-BvSJ2ro7Tnu85FAz .icon-shape .label rect,#mermaid-svg-BvSJ2ro7Tnu85FAz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-BvSJ2ro7Tnu85FAz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-BvSJ2ro7Tnu85FAz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-BvSJ2ro7Tnu85FAz :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

内存放大器2MB JPEG → 48MB RGBA

width/height只影响绘制尺寸

cacheWidth/cacheHeight影响解码输出尺寸

Key 阶段生成 ImageProvider 的 key

Fetch 阶段从网络/磁盘/内存获取压缩字节

Decode 阶段压缩字节 → 未压缩像素矩阵

Cache 阶段解码结果进入 ImageCache

Paint 阶段按布局尺寸绘制到屏幕

内存峰值宽度 × 高度 × 4 字节

布局尺寸逻辑像素

解码尺寸物理像素

关键结论： 内存问题发生在 Decode 阶段，cacheWidth/cacheHeight 的作用点在解码器，而 width/height 只影响 Paint 阶段的绘制尺寸。

2.1 解码是内存的“放大器”：压缩字节 → 未压缩像素

Flutter 的图片管线包含五个阶段：Key → Fetch → Decode → Cache → Paint。内存问题发生在 Decode 阶段：压缩的字节（JPEG、PNG、WebP）被解码器展开为 dart:ui.Image，即“原始像素，宽度 × 高度 × 4 字节”。一张 4000×3000 的图片，在这个阶段从“约 2MB 的压缩数据”变成了“48MB 的 RGBA 像素矩阵”。

这个放大倍率不是恒定的，它取决于压缩率、图片内容的复杂度和格式。一张纯色 PNG 的压缩率极高，磁盘上可能只有几十 KB，但解码后仍然是 宽度 × 高度 × 4 字节；一张高质量的 JPEG 压缩率较低，磁盘上可能有 5MB，但解码后同样是那个像素矩阵。决定内存的是解码后的尺寸，不是文件大小。这就是为什么“只加载缩略图”和“只加载头像”仍然可能导致 OOM：如果源图是 12MP 的相机照片，即使它在屏幕上只显示为 48×48 的圆形头像，默认的解码行为仍然会把整张 12MP 图片展开到内存中，然后再缩小绘制。

2.2 cacheWidth/cacheHeight 的作用点在解码器，不在布局引擎

cacheWidth 和 cacheHeight 之所以能将 4K 图片的内存从 30MB 降到 330KB，是因为它们改变了 Decode 阶段本身。instantiateImageCodecFromBuffer 的文档说明，这两个参数“指示解码图片的目标尺寸”，引擎会在解码时直接输出缩小后的像素矩阵，而不是先解码全尺寸再缩小。Image 文档对此的表述是：“引擎将在指定尺寸解码并存储图片，而不是图片的自然尺寸。这可以显著减少内存占用”。

这与 Image Widget 的 width/height 参数有本质区别：width/height 影响的是 Paint 阶段的绘制尺寸，解码仍然按原始尺寸进行，内存已经支付了。cacheWidth/cacheHeight 影响的是 Decode 阶段的输出尺寸，内存在这张图片的生命周期中根本不会被分配。一个常见的误解是“我在 Image 上设置了 width: 200，所以内存应该很小”——布局尺寸和内存尺寸是两个独立的维度，前者不约束后者。

2.3 ImageCache 的 LRU 只约束“缓存”，不约束“存活”

ImageCache 的 LRU 机制管理的是 _cache 中的条目：当缓存的总字节数超过 maximumSizeBytes（默认 100MB）或条目数超过 maximumSize（默认 1000）时，最久未使用的条目被驱逐。但这个机制有一个结构性的边界：它不驱逐 live 的图片。

一张图片在以下情况下是 live 的：它至少有一个监听者（例如一个正在显示的 Image Widget），或者它通过 precacheImage 被钉住，或者它被 ImageStreamCompleterHandle 持有。precacheImage 的文档对此的警告是直接的：图片“会保持在内存中至少直到调用者移除监听者，即使它本来不适合缓存”；“调用者应谨慎将大图或大量图片钉在内存中，因为这可能导致 OOM”。ImageCache 的 clear() 方法“驱逐所有 pending 和 keepAlive 条目”，但要清除 live 引用，“使用 clearLiveImages”——这从 API 的层面确认了 live 与 cache 是两套不同的管理机制。

一个具体的后果是：如果开发者为了“优化体验”而对一个相册的每一张图片都调用了 precacheImage，这些图片在预加载完成后并没有立即被任何 Widget 监听，但 precacheImage 的 Future 完成之前它会保持一个监听者，完成后监听者被移除——如果此时图片没有被任何 Widget 接管，它可能进入缓存；但如果它已经因为尺寸超过 maximumSizeBytes 而无法进入缓存，它会在监听者移除后被释放。真正危险的是“图片同时被多个 Widget 监听，或者被一个不释放的 ImageStreamCompleterHandle 持有”的场景：此时 LRU 的字节上限对这些 live 图片完全无效。

2.4 ListView 的“懒构建”不自动等于“内存释放”

第11课建立了 ListView.builder 的懒加载语义：屏幕外的条目不构建。但懒构建和内存释放是两件不同的事。Flutter 的 issue #92378 记录了一个开发者的精确观察：“内存只增不减，随着从网络下载的新图片不断累积；当 Widget 被 dispose 时，内存从未被自动释放”；他的期望之一是“在 ListView.builder 中只为可见条目（或加上 cacheExtent 限制）保持图片在内存中”，但实际行为并非如此；他尝试了 automaticKeepAlive 参数，“无论设为 true 还是 false 都不改变任何东西”；即使使用了 ResizeImage，“OOM 仍然不可避免”。

这个 issue 揭示的根因是：ListView.builder 销毁的是列表项的 Element 和 State，它不负责清理 ImageCache 中的缓存条目。当一个列表项滚出视口并被销毁时，它对应的 Image Widget 的监听者被移除，图片从 live 变为非 live，进入 ImageCache 的 LRU 管理。如果列表项足够多、图片足够大，ImageCache 会在滚动过程中不断累积解码后的图片，直到达到 100MB 的默认上限才开始驱逐。在这个累积过程中，内存峰值可能远高于“可见条目”的理论值。如果图片尺寸接近或超过 maximumSizeBytes，它们甚至无法进入缓存（putIfAbsent 的文档：“大于 maximumSizeBytes 的图片不会被缓存”），每次重新进入视口都需要重新解码，造成 CPU 和内存的反复抖动。

keepAlive 机制会进一步加剧这个问题。Image 的 keepAlive 属性“决定渲染的图片是否应该在例如滚出 ListView 视图后仍然被保留”。当 keepAlive 为 true 时，图片被显式钉住，即使列表项被销毁，图片仍然留在内存中。这在“需要保持滚动位置和图片状态”的场景中是合理的，但在长列表中，它会把“按需加载”退化为“累积保留”。

三、经典故障模式与深入案例

四种经典故障模式，本质上是“解码尺寸”和“存活数量”两个维度的失控组合：

#mermaid-svg-Pu7Ffy6GiAyRu3le{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Pu7Ffy6GiAyRu3le .error-icon{fill:#552222;}#mermaid-svg-Pu7Ffy6GiAyRu3le .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Pu7Ffy6GiAyRu3le .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .marker.cross{stroke:#333333;}#mermaid-svg-Pu7Ffy6GiAyRu3le svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Pu7Ffy6GiAyRu3le p{margin:0;}#mermaid-svg-Pu7Ffy6GiAyRu3le .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster-label text{fill:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster-label span{color:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster-label span p{background-color:transparent;}#mermaid-svg-Pu7Ffy6GiAyRu3le .label text,#mermaid-svg-Pu7Ffy6GiAyRu3le span{fill:#333;color:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .node rect,#mermaid-svg-Pu7Ffy6GiAyRu3le .node circle,#mermaid-svg-Pu7Ffy6GiAyRu3le .node ellipse,#mermaid-svg-Pu7Ffy6GiAyRu3le .node polygon,#mermaid-svg-Pu7Ffy6GiAyRu3le .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .rough-node .label text,#mermaid-svg-Pu7Ffy6GiAyRu3le .node .label text,#mermaid-svg-Pu7Ffy6GiAyRu3le .image-shape .label,#mermaid-svg-Pu7Ffy6GiAyRu3le .icon-shape .label{text-anchor:middle;}#mermaid-svg-Pu7Ffy6GiAyRu3le .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .rough-node .label,#mermaid-svg-Pu7Ffy6GiAyRu3le .node .label,#mermaid-svg-Pu7Ffy6GiAyRu3le .image-shape .label,#mermaid-svg-Pu7Ffy6GiAyRu3le .icon-shape .label{text-align:center;}#mermaid-svg-Pu7Ffy6GiAyRu3le .node.clickable{cursor:pointer;}#mermaid-svg-Pu7Ffy6GiAyRu3le .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .arrowheadPath{fill:#333333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Pu7Ffy6GiAyRu3le .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Pu7Ffy6GiAyRu3le .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Pu7Ffy6GiAyRu3le .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster text{fill:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le .cluster span{color:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Pu7Ffy6GiAyRu3le .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Pu7Ffy6GiAyRu3le rect.text{fill:none;stroke-width:0;}#mermaid-svg-Pu7Ffy6GiAyRu3le .icon-shape,#mermaid-svg-Pu7Ffy6GiAyRu3le .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Pu7Ffy6GiAyRu3le .icon-shape p,#mermaid-svg-Pu7Ffy6GiAyRu3le .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Pu7Ffy6GiAyRu3le .icon-shape .label rect,#mermaid-svg-Pu7Ffy6GiAyRu3le .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Pu7Ffy6GiAyRu3le .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Pu7Ffy6GiAyRu3le .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Pu7Ffy6GiAyRu3le :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

图片内存 = 解码尺寸 × 存活数量

解码尺寸失控

存活数量失控

模式一布局尺寸不约束解码尺寸48×48 头像解码 48MB

模式二动画图片 cacheWidth 静默失效GIF/WebP/APNG 不生效

模式三precacheImage 钉住大图绕过 LRU 驱逐

模式四大图无法进入缓存每次滚动重新解码

修复：cacheWidth = 布局 × DPR

修复：服务端缩略图 + 数量控制

修复：仅限关键小图预加载

修复：缩小解码尺寸放入缓存

四种模式对应四种不同的修复路径，不能用一个统一的“加 cacheWidth”解决所有问题。

模式一：12MP 头像的 48MB 解码——布局尺寸不约束解码尺寸

一个聊天或社交应用的头像通常显示为 48×48 或 64×64 的圆形。开发者写下 Image.network(user.avatarUrl, width: 48, height: 48, fit: BoxFit.cover)，视觉上完全正确，但内存中解码的是原始图片的全尺寸像素。如果用户的头像是从手机相机上传的 4000×3000 照片，每次解码都会产生约 48MB 的 RGBA 数据。一个滚动列表中有 20 个这样的头像进入过视口，ImageCache 中的累积内存可以轻松达到数百 MB，而屏幕上每个头像的视觉尺寸只有 48 逻辑像素。

这个模式的修复是精确的：在 Image.network 上添加 cacheWidth 和 cacheHeight，值为“布局逻辑尺寸 × devicePixelRatio”。对于 48 逻辑像素的头像，在 DPR 为 3 的设备上，cacheWidth: 144 就足够清晰，解码内存从 48MB 降到约 83KB（144×144×4 字节）——减少约 580 倍。ResizeImage 是同一机制在 ImageProvider 层面的表达：“ResizeImage 与显式 provider 是同一机制，当你组合 provider 而不是使用 Image 构造函数时很有用”。

模式二：动画贴纸网格的 OOM——cacheWidth 静默失效

一个社交应用的“贴纸选择”网格使用 GridView.builder 展示 40 张动画 GIF，每张 GIF 的源尺寸可能是 500×500，磁盘大小从几百 KB 到几 MB 不等。开发者给每个 Image.network 加上了 cacheWidth: 200，期望内存可控。但引擎的 PR 明确指出：“cacheWidth/cacheHeight 和 ResizeImage 对动画 GIF、WebP 和 APNG 图片没有效果，这是高内存占用的一个常见来源（例如动画贴纸的网格）”。

实际的解码内存是 40 × 500 × 500 × 4 字节 ≈ 40MB 的单帧像素数据；动画图片还需要为解码帧的缓存分配额外内存，而帧缓存的上限与压缩尺寸相关（一个 decodedCacheRatioCap 的设计意图是限制“缓存非必要解码帧”的内存，例如“400KB 的 GIF 最多允许使用 800KB 的内存来缓存解码帧”）。在一个网格中同时展示 20 张可见贴纸，加上 cacheExtent 预加载的条目，再加上帧缓存，内存峰值可以轻松超过 ImageCache 的 100MB 默认上限，而 cacheWidth 对这些图片完全没有起到限制作用。

这个模式的修复方向不是“给 cacheWidth 换一个值”（它对动画格式无效），而是：在服务端提供已经缩小尺寸的贴纸缩略图，让客户端解码的源尺寸本身就接近显示尺寸；或者在客户端对动画图片使用专门的、支持尺寸约束的解码路径（如果引擎版本支持），并对不可约束的动画资源采取更严格的数量控制（减少同时可见的动画数量、降低 cacheExtent、避免对动画图片使用 precacheImage）。

模式三：precacheImage 的“好心办坏事”——预加载把大图钉在内存中

一个开发者为了消除页面切换时的图片闪烁，在 didChangeDependencies 中对即将展示的一组高清商品图调用了 precacheImage。precacheImage 的文档确认了它的用途：“预取一张图片到图片缓存中。返回的 Future 在 ImageProvider 产生的第一张图片可用或加载失败时完成”。但文档紧接着的警告被忽略了：“图片将保持在内存中至少直到调用者从流中移除监听者，即使它本来不适合缓存。调用者应谨慎将大图或大量图片钉在内存中，因为这可能导致 OOM”。

如果这组商品图是 2000×2000 的高清图，每张解码约 16MB，预加载 10 张就是 160MB，已经超过了 ImageCache 的默认 100MB 上限。由于 precacheImage 在 Future 完成之前会保持一个监听者，这些图片在预加载阶段是 live 的，LRU 无法驱逐它们。如果预加载的图片数量继续增长，或者用户在预加载完成之前就离开了页面，内存峰值会显著超过“正常使用”时的水平。precacheImage 的正确使用边界是：只对关键的小尺寸图片（例如启动屏 logo、少量首屏图标）使用，并且配合 cacheWidth/cacheHeight 限制解码尺寸；不要对高清大图或大量图片批量调用它。

模式四：ImageCache 的“驱逐抖动”——大图无法进入缓存，每次滚动都重新解码

putIfAbsent 的文档有一条容易被忽略的规则：“大于 maximumSizeBytes 的图片不会被缓存，也不会导致缓存中的其他图片被驱逐”。如果一张图片的解码后字节数超过 100MB（例如一张 6000×6000 的图片，解码后约 137MB），它永远不会进入 ImageCache。每次它出现在视口中，都需要重新从网络或磁盘加载、重新解码；每次它离开视口，内存被释放。在快速滚动中，这会表现为频繁的 CPU 峰值和内存的锯齿状波动，而不是稳定增长。如果多张这样的图片同时可见，它们都是 live 的，合计内存可能直接触发 OOM，而 ImageCache 的 100MB 上限对这些图片从未生效。

Flutter 在 1.17 中对此做了一个重要的变更：“ImageCache 的 maxByteSize 不再自动增大以容纳大图”。在此之前，“当加载字节数大于 ImageCache 的 maxByteSize 的图片时，Flutter 会永久增大 maxByteSize 的值来容纳它们”，这“有时导致 maxByteSize 膨胀，使内存受限的系统更难工作”。变更后的逻辑是：大图如果无法放入缓存，就不缓存，而不是让缓存为了容纳它而膨胀。这个设计的意图是保护内存，但它对大图的直接后果就是模式四描述的“每次重新解码”。

这个模式的修复只有一条根本路径：缩小解码尺寸，让图片能够舒适地放入缓存。cacheWidth/cacheHeight 或 ResizeImage 在这里不是“可选优化”，而是让缓存机制能够正常工作的前提。如果源图确实需要以全分辨率展示（例如一个可缩放查看的图片查看器），那么应该接受“这张图片不进入缓存”的事实，并为它设计独立的生命周期管理（在退出查看器时显式 evict），而不是依赖 ImageCache 的自动行为。

四、系统性排查方法论

第一步：先计算“理论解码内存”，而不是猜测

在打开 DevTools 之前，先对怀疑的图片做一次算术。对每一张图片，找到它的源像素尺寸（不是文件大小，不是布局尺寸），然后计算 宽度 × 高度 × 4 字节。一张 4000×3000 的图片是 48MB；一张 1920×1080 的图片是 8.3MB；一张 500×500 的图片是 1MB。把这个数字乘以“同时可见的图片数量 + cacheExtent 预加载的数量 + 可能被 precacheImage 钉住的数量”。如果乘积接近或超过设备可用内存的合理阈值（在低端 Android 设备上，一个 Flutter 应用的图片内存预算通常在 100–200MB 量级），OOM 的风险就是可计算的，而不是“偶发”的。

flutter 社区的一些工具（如 buoy 的 estDecodedBytes）提供了 RGBA8888 解码内存的估算，其文档明确说明这是“解码位图内存”，不包含全局图片缓存、编码字节和 GPU 开销。这个估算是一个有用的下界，真实峰值会更高。

第二步：在 DevTools 的 Memory 视图中区分“图片内存”与“其他内存”

DevTools 的 Memory 视图可以按类型过滤，但图片内存的归因需要一些技巧。一个实用的方法是：在 Profile 模式下运行，滚动到怀疑的页面，记录内存快照；然后滚动离开该页面，触发 GC，再记录一次。如果内存没有显著下降，说明图片仍然被 live 引用或缓存持有。结合 ImageCache 的状态（imageCache.currentSizeBytes、imageCache.liveImageCount），可以区分“缓存中的图片”和“live 的图片”：liveImageCount 高而 currentSizeBytes 低，意味着大量图片正在被监听或钉住，但未进入 LRU 管理。

ImageCache 的 clear() 和 clearLiveImages() 可以在调试中作为诊断手段：如果调用 clear() 后内存下降，说明问题在缓存中的非 live 条目；如果只有调用 clearLiveImages() 后才下降，说明有图片被 precacheImage 或 ImageStreamCompleterHandle 钉住，需要检查预加载和手动持有的引用。

第三步：检查每一张 Image 的 cacheWidth/cacheHeight 是否与布局尺寸和 DPR 匹配

对代码库中的每一处 Image（network、asset、file、memory），检查它是否设置了 cacheWidth/cacheHeight。如果设置了，检查它的值是否等于“布局逻辑尺寸 × devicePixelRatio”。一个常见的错误是只设置了 width/height（布局），而没有设置 cacheWidth/cacheHeight（解码）；另一个常见错误是 cacheWidth 的值远大于布局尺寸 × DPR（例如在 48 逻辑像素的头像上设置 cacheWidth: 500），这虽然比不设好，但仍然浪费了内存。对于没有设置 cacheWidth/cacheHeight 的 Image，问：这张图片的源尺寸是否可能远大于显示尺寸？ 如果答案是“可能”或“不知道”，它就是一个需要修复的候选。

第四步：识别动画图片并确认尺寸参数是否有效

对每一张 Image，确认源格式是否为 GIF、WebP 或 APNG。如果是，cacheWidth/cacheHeight 和 ResizeImage 在这些格式上不生效（根据当前引擎的实现）。排查时需要检查：这些动画图片的源尺寸是否接近显示尺寸？ 如果源尺寸远大于显示尺寸，且无法在客户端通过解码参数约束，那么服务端提供缩小尺寸的缩略图是唯一的根本解决方案。此外，检查动画图片的数量和 cacheExtent：在动画贴纸网格中，减少预加载范围、避免批量 precacheImage，可以显著降低峰值内存。

第五步：区分“泄漏”与“缓存”与“live 钉住”

图片内存“不释放”可能有三种不同的原因，修复方向完全不同。缓存：图片在 ImageCache 的 LRU 中，等待被驱逐或复用；这是正常行为，内存会随滚动和缓存压力波动，最终受 maximumSizeBytes 约束。live 钉住：图片被 precacheImage、ImageStreamCompleterHandle 或一个未移除的监听者持有；这是真正的“不释放”，需要检查预加载和手动监听的生命周期。Widget 泄漏：Image Widget 本身被一个未释放的 State 或全局引用持有，导致它的监听者永远存在；这需要用 DevTools 的 Allocation Tracker 或 leak_tracker 来定位。三者的排查路径不同：缓存用 ImageCache 状态检查，live 钉住用 clearLiveImages 诊断，Widget 泄漏用引用链分析。

五、修复方案：按“解码尺寸”和“存活数量”两个维度分层

修复方案按“解码尺寸”和“存活数量”两个维度分层，决策流程如下：

#mermaid-svg-oIPM1uC0bousjbU9{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-oIPM1uC0bousjbU9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-oIPM1uC0bousjbU9 .error-icon{fill:#552222;}#mermaid-svg-oIPM1uC0bousjbU9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-oIPM1uC0bousjbU9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-oIPM1uC0bousjbU9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-oIPM1uC0bousjbU9 .marker.cross{stroke:#333333;}#mermaid-svg-oIPM1uC0bousjbU9 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-oIPM1uC0bousjbU9 p{margin:0;}#mermaid-svg-oIPM1uC0bousjbU9 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-oIPM1uC0bousjbU9 .cluster-label text{fill:#333;}#mermaid-svg-oIPM1uC0bousjbU9 .cluster-label span{color:#333;}#mermaid-svg-oIPM1uC0bousjbU9 .cluster-label span p{background-color:transparent;}#mermaid-svg-oIPM1uC0bousjbU9 .label text,#mermaid-svg-oIPM1uC0bousjbU9 span{fill:#333;color:#333;}#mermaid-svg-oIPM1uC0bousjbU9 .node rect,#mermaid-svg-oIPM1uC0bousjbU9 .node circle,#mermaid-svg-oIPM1uC0bousjbU9 .node ellipse,#mermaid-svg-oIPM1uC0bousjbU9 .node polygon,#mermaid-svg-oIPM1uC0bousjbU9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-oIPM1uC0bousjbU9 .rough-node .label text,#mermaid-svg-oIPM1uC0bousjbU9 .node .label text,#mermaid-svg-oIPM1uC0bousjbU9 .image-shape .label,#mermaid-svg-oIPM1uC0bousjbU9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-oIPM1uC0bousjbU9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-oIPM1uC0bousjbU9 .rough-node .label,#mermaid-svg-oIPM1uC0bousjbU9 .node .label,#mermaid-svg-oIPM1uC0bousjbU9 .image-shape .label,#mermaid-svg-oIPM1uC0bousjbU9 .icon-shape .label{text-align:center;}#mermaid-svg-oIPM1uC0bousjbU9 .node.clickable{cursor:pointer;}#mermaid-svg-oIPM1uC0bousjbU9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-oIPM1uC0bousjbU9 .arrowheadPath{fill:#333333;}#mermaid-svg-oIPM1uC0bousjbU9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-oIPM1uC0bousjbU9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-oIPM1uC0bousjbU9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oIPM1uC0bousjbU9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-oIPM1uC0bousjbU9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oIPM1uC0bousjbU9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-oIPM1uC0bousjbU9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-oIPM1uC0bousjbU9 .cluster text{fill:#333;}#mermaid-svg-oIPM1uC0bousjbU9 .cluster span{color:#333;}#mermaid-svg-oIPM1uC0bousjbU9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-oIPM1uC0bousjbU9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-oIPM1uC0bousjbU9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-oIPM1uC0bousjbU9 .icon-shape,#mermaid-svg-oIPM1uC0bousjbU9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oIPM1uC0bousjbU9 .icon-shape p,#mermaid-svg-oIPM1uC0bousjbU9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-oIPM1uC0bousjbU9 .icon-shape .label rect,#mermaid-svg-oIPM1uC0bousjbU9 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oIPM1uC0bousjbU9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-oIPM1uC0bousjbU9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-oIPM1uC0bousjbU9 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

是

否（动画）

是

否（ImageProvider）

是

否

是

否

遇到图片内存问题

图片是静态格式？JPEG/PNG/BMP

是否直接使用Image 构造函数？

第五层：源尺寸约束服务端缩略图 + 数量控制

第一层：cacheWidth/cacheHeight解码尺寸 = 布局 × DPR

第二层：ResizeImage 包裹注意 key 稳定性

是否在长列表中？

第三层：控制 cacheExtent 和 keepAlive

是否需要预加载？

第四层：precacheImage 纪律仅限关键小图 ≤ 2-3 张

第六层：必要时调整 ImageCache 预算但不要当作修复

验证：低端真机 + Profile 模式

分层原则： 先限制解码尺寸（第一、二、五层），再控制存活数量（第三、四层），最后才考虑调整缓存预算（第六层）。

第一层：对静态图片，用 cacheWidth/cacheHeight 将解码尺寸限制到显示尺寸

这是收益最直接、适用面最广的修复。对每一张源尺寸可能大于显示尺寸的静态图片（JPEG、PNG、BMP），在 Image.network/Image.asset/Image.file 上添加 cacheWidth 和 cacheHeight，值为“布局逻辑尺寸 × devicePixelRatio”。如果只关心一个维度（例如宽度受限、高度按比例），可以只指定 cacheWidth，引擎会按原始宽高比缩放另一个维度。

换算公式是：

final dpr = MediaQuery.devicePixelRatioOf(context);
Image.network(
url,
width: 200, // 布局：逻辑像素
cacheWidth: (200 * dpr).round(), // 解码：物理像素
fit: BoxFit.cover,
)

一个需要注意的边界是 allowUpscaling：instantiateImageCodecFromBuffer 的文档说明，默认情况下 cacheWidth/cacheHeight “被钳制到原始图片的固有宽度和高度”，以避免“不必要的内存使用”；也就是说，如果传入的 cacheWidth 大于源图宽度，解码尺寸不会超过源图，不会产生放大后的模糊。如果确实需要放大显示，应该“缩放图片绘制到的画布”，而不是依赖解码放大。

第二层：对 ImageProvider 组合场景，用 ResizeImage 包裹

当图片不是直接通过 Image 构造函数加载，而是作为 ImageProvider 传递（例如 DecorationImage、FadeInImage、CachedNetworkImage 的 imageProvider），ResizeImage 是等效的工具。一个图片缓存包的文档建议：“为了以更小的尺寸解码（推荐用于缩略图），将其包裹在 ResizeImage 中”。ResizeImage(NetworkImage(url), width: targetWidth, height: targetHeight) 的 width/height 是解码尺寸（物理像素） ，与 cacheWidth/cacheHeight 的语义一致。

ResizeImage 有一个需要留意的陷阱：如果它的 width/height 来自一个会在布局中变化的约束（例如每一帧都不同的 constraints.maxWidth），每次尺寸变化都会产生一个新的 ImageProvider key，导致重新解码。一篇图片管线文章对此的表述是：“ResizeImage 的尺寸来自一个按像素变化的布局时，key 会变化，所以它会重新解码”；修复方式是“将 ResizeImage 的尺寸舍入到一个稳定的桶，而不是传递原始的布局约束”。这意味着 ResizeImage 的尺寸应该来自稳定的设计值或断点，而不是每一帧重新计算的像素值。

第三层：对 ListView/GridView 中的图片，控制 cacheExtent 和 keepAlive

ListView.builder 的 cacheExtent 控制视口之外预加载和保留的区域大小。默认值在图片密集的列表中可能导致过多的图片同时存活；将 cacheExtent 设为一个适度的值（例如可见区域高度的 1–1.5 倍），可以减少“即将进入视口但尚未可见”的图片占用的内存。如果列表项包含的是大图或动画图片，较小的 cacheExtent 可以显著降低峰值内存，代价是快速滑动时可能出现短暂的白屏。

Image 的 keepAlive 属性“决定渲染的图片是否应该在例如滚出 ListView 视图后仍然被保留”。对于大多数图片列表，keepAlive 应该保持为 false（默认值），让滚出视口的图片进入正常的缓存和驱逐流程。只有当图片是“小尺寸的、频繁滚回视口的、重新解码成本明显高于内存成本”时（例如一个表情选择面板中的小图标），才考虑将 keepAlive 设为 true 并配合 cacheWidth 严格限制解码尺寸。

第四层：对 precacheImage 建立“仅限关键小图”的纪律

precacheImage 的合理场景是：一张确定会在下一页立即显示、尺寸受限、数量很少的图片（例如启动屏过渡到首页的 hero 图、一个 PageView 的第一张图）。使用时的检查清单是：这张图片是否设置了 cacheWidth/cacheHeight？预加载的数量是否不超过 2–3 张？预加载的时机是否在图片确实即将被使用之前，而不是“提前把所有可能用到的图片都加载了”？如果一个页面需要预加载的图片超过 3 张，或者图片的源尺寸很大，precacheImage 的收益（减少加载闪烁）很可能小于它的内存代价（将图片钉在内存中，绕过 LRU）。

第五层：对动画图片，从“解码尺寸约束”转向“源尺寸约束”

由于 cacheWidth/cacheHeight 和 ResizeImage 对动画 GIF/WebP/APNG 当前不生效（引擎 PR 的明确表述），客户端侧的修复不能依赖这些参数。可行的方向是：在服务端或构建时生成尺寸更小的动画缩略图，让客户端解码的源尺寸本身就接近显示尺寸；如果无法控制源，减少同时可见的动画图片数量（通过布局限制或分页），并避免对动画图片使用 precacheImage。在 GridView 中展示动画贴纸时，cacheExtent 应该设置得比静态图片列表更小，因为每一张动画图片的内存成本包含单帧像素和帧缓存两层。

第六层：必要时调整 ImageCache 的预算，但不要把调大当作修复

ImageCache 的默认上限是 1000 张和 100MB。在低端设备上，100MB 的图片缓存可能已经过大；可以适当调小 maximumSizeBytes，让 LRU 更早驱逐，降低峰值内存（代价是滚动时更频繁地重新解码）。在高端设备或图片密集的专用页面，可以适度调大，但这必须是“在解码尺寸已经受限、存活数量已经控制”之后的调整，而不是用更大的缓存去容纳未缩小的图片。Flutter 的 breaking change 明确反对“为了容纳大图而增大 maxByteSize”的做法：“不再自动增大 ImageCache 的 maxByteSize 来容纳大图”；迁移指南的方向是“调整图片加载逻辑，确保图片能合适地放入你选择的 maxByteSize”，而不是反过来让缓存适应大图。

六、预防体系：让“解码尺寸”成为图片加载的默认审查项

原则一：每一张 Image 都必须回答“解码尺寸是多少”

在团队规范中，将 cacheWidth/cacheHeight（或 ResizeImage 的 width/height）作为图片加载的默认配置，而不是“等到 OOM 才加的优化”。任何新增的 Image.network/Image.asset/Image.file，在 code review 中都需要回答：这张图片的源尺寸可能有多大？显示尺寸是多少？解码尺寸是否被限制到了显示尺寸 × DPR？ 如果源尺寸不确定（例如用户上传的头像、第三方 URL），默认必须设置解码尺寸限制。PreferImageSizeConstraintsRule 这类 lint 的警告信息正是这个原则的自动化版本：“Warns when Image lacks cacheWidth/cacheHeight for memory optimization. Images decoded at full resolution consume excessive memory”。

原则二：区分“布局尺寸”和“解码尺寸”，并确保换算正确

width/height 是逻辑像素的布局尺寸，cacheWidth/cacheHeight 是物理像素的解码尺寸。在团队文档中明确这个换算关系：解码尺寸 = 布局逻辑尺寸 × devicePixelRatio。对每一个设置了 cacheWidth 的 Image，检查它的值是否基于布局尺寸和 DPR 计算，而不是基于源图尺寸或一个凭直觉填写的数字。一个常见的错误模式是“只在 Image 上设置了 width: 200，然后以为内存就是 200×高度”——布局尺寸不改变解码行为。

原则三：对动画图片建立独立的资源规范

由于动画图片的尺寸参数当前不生效，对 GIF/WebP/APNG 的资源管理不能沿用静态图片的“加 cacheWidth”策略。团队规范应该要求：动画资源在入库或服务端处理时就被限制到接近显示尺寸，而不是依赖客户端解码缩小；动画图片的列表使用更小的 cacheExtent；禁止对动画图片批量 precacheImage。在资源审查中，动画图片的“源尺寸”和“同时可见数量”是两个需要显式确认的指标。

原则四：把 precacheImage 当作“稀缺资源”而不是“通用优化”

precacheImage 的文档警告“调用者应谨慎将大图或大量图片钉在内存中”。在团队规范中，将 precacheImage 的使用限制在“关键的小尺寸图片、数量不超过 2–3 张、并且已设置解码尺寸限制”的场景中。任何新增的 precacheImage 调用都需要说明：这张图片为什么不能被正常的按需加载覆盖？预加载的内存代价是否已经被计算过？

原则五：在 CI 或测试中监控图片解码内存的“理论峰值”

一个可以在 Widget 测试或集成测试中执行的检查是：对关键图片页面，收集所有可见图片的源尺寸（或从资源清单中读取），计算解码内存的理论总和，并与一个预算阈值比较。如果理论峰值超过阈值，测试失败或发出警告。这个检查不需要真正触发 OOM，它基于“解码尺寸 × 存活数量”的算术，可以在代码合并之前捕获“又引入了一张 4000×3000 的未限制图片”这样的回归。

原则六：在真机、低端设备和 Profile 模式下验证

图片内存问题在 Debug 模式、模拟器和高内存设备上往往不可见。Debug 模式的性能特征与 Release 不同，模拟器的内存限制与真机不同，高端设备的大内存会掩盖峰值。验收应该在至少一台低端 Android 真机上、Profile 模式下进行，观察滚动和页面切换时的内存曲线。低端设备是 OOM 最先暴露的地方，也是“解码尺寸未受限”和“live 图片过多”这两个根因最容易同时发作的地方。

七、课后习题（15道）

习题1（单选）

一张 4000×3000 的 JPEG 在 Flutter 中默认解码后，占用的近似内存是：

A. 约 2MB，与磁盘文件大小相同 B. 约 12MB，等于宽度 × 高度 × 1 字节 C. 约 48MB，等于宽度 × 高度 × 4 字节 D. 约 4000KB，等于宽度 × 高度 / 3000

参考答案：C

解读： Flutter 将图片以未压缩形式存储在内存中以便渲染，每个像素占 4 字节（RGBA）。4000 × 3000 × 4 = 48,000,000 字节 ≈ 48MB。磁盘上的文件大小（约 2MB）是压缩后的字节，与解码后的像素矩阵没有直接比例关系。这正是“文件大小与内存占用脱钩”的核心。

习题2（判断）

在 Image.network(url, width: 48, height: 48) 中，width 和 height 参数会限制图片的解码尺寸，因此内存占用很小。

参考答案：错误

解读： width 和 height 影响的是 Paint 阶段的布局和绘制尺寸，解码仍然按图片的原始尺寸进行。如果源图是 4000×3000，即使显示为 48×48，内存中仍然会分配约 48MB 的像素数据。要限制解码尺寸，必须使用 cacheWidth/cacheHeight（物理像素）或 ResizeImage。

习题3（多选）

cacheWidth 和 cacheHeight 参数的语义包括：

A. 它们指示引擎在解码时将图片解码到指定尺寸 B. 它们使用逻辑像素作为单位，与 width/height 相同 C. 如果只指定其中一个，另一个维度会按原始宽高比缩放 D. 当两者都省略时，图片按原生分辨率解码

参考答案：A、C、D

解读： A 是基本语义。C 和 D 来自 instantiateImageCodecFromBuffer 的文档：“当只指定其中一个时，省略的维度将按原始宽高比缩放；当两者都省略时，图片将按其原生分辨率解码”。B 是错误的：cacheWidth/cacheHeight 是物理像素（解码尺寸），而 width/height 是逻辑像素（布局尺寸）。把逻辑像素直接传给 cacheWidth，在 2x/3x 屏幕上会导致模糊。

习题4（场景分析）

一个 48×48 逻辑像素的头像，源图是 4000×3000，设备 devicePixelRatio 为 3。请计算：不设置 cacheWidth 时的解码内存，以及设置正确的 cacheWidth 后的解码内存。并说明这个案例的修复原则。

参考答案： 不设置 cacheWidth 时，解码内存为 4000 × 3000 × 4 ≈ 48MB。正确的 cacheWidth = 48 × 3 = 144 物理像素，解码内存为 144 × 144 × 4 ≈ 83KB。修复原则是“解码尺寸应接近显示尺寸的物理像素值，而不是源图尺寸或布局逻辑尺寸”。这个案例展示了布局尺寸（48 逻辑像素）与解码尺寸（144 物理像素）的换算关系；如果错误地设置 cacheWidth: 48，在 DPR 3 的屏幕上图片会模糊；如果设置 cacheWidth: 4000，则完全没有限制内存。

习题5（单选）

ImageCache 的默认 maximumSizeBytes 是：

A. 10MB B. 50MB C. 100MB D. 500MB

参考答案：C

解读： ImageCache 的类文档明确写道：“Implements a least-recently-used cache of up to 1000 images, and up to 100 MB”。这个 100MB 是“缓存中的图片”的字节上限，它不约束 live 图片（正在被监听或被 precacheImage 钉住的图片）。理解这一点是排查“缓存没超但内存超了”的关键。

习题6（多选）

关于 ImageCache 的 live 引用，以下说法正确的是：

A. 一张图片在至少有一个监听者时被认为是 live 的 B. live 图片不受 maximumSizeBytes 的驱逐约束 C. precacheImage 会在 Future 完成前保持监听者，将图片钉在内存中 D. clear() 方法会同时清除 live 引用

参考答案：A、B、C

解读： A 来自 ImageCache 文档对 live 的定义：“An image is considered live if its ImageStreamCompleter’s listener count has never dropped to zero after adding at least one listener”。B 是正确的：LRU 的字节上限管的是缓存条目，live 图片可以绕过它；precacheImage 的警告“即使它本来不适合缓存”正是这个机制的表现。C 是正确的：precacheImage 在 Future 完成之前会保持监听者。D 是错误的：clear() 驱逐的是 pending 和 keepAlive 条目；要清除 live 引用，需要使用 clearLiveImages()。

习题7（判断）

cacheWidth 和 ResizeImage 对所有图片格式都有效，包括动画 GIF 和 WebP。

参考答案：错误

解读： 引擎的 PR 明确指出：“cacheWidth/cacheHeight 和 ResizeImage 对动画 GIF、WebP 和 APNG 图片没有效果，这是高内存占用的一个常见来源（例如动画贴纸的网格）”。这意味着在动画图片场景中，即使代码中写了 cacheWidth，解码仍然按原始尺寸进行，内存限制参数是静默失效的。修复方向不是在客户端调整参数值，而是从源尺寸（服务端缩略图）和数量控制入手。

习题8（场景分析）

一个 ListView.builder 滚动浏览 200 张高清图片，每张图片源尺寸 2000×2000（解码约 16MB）。开发者使用了 ListView.builder（懒加载），但滚动过程中内存持续上升，最终 OOM。请解释为什么懒加载没有阻止 OOM，并给出至少两个修复方向。

参考答案： 懒加载（ListView.builder）只保证屏幕外的列表项不被构建，它不负责清理 ImageCache 中已经解码的图片。当图片进入视口时，它们被解码并进入 ImageCache；当列表项滚出视口时，Widget 被销毁，但图片作为非 live 条目留在缓存中，直到 LRU 达到 100MB 上限才开始驱逐。在滚动过程中，缓存不断累积，而 200 张图片的累计解码内存（约 3.2GB）远超 100MB，OOM 在达到驱逐平衡之前就会发生。此外，如果单张图片的 16MB 接近但不超过上限，缓存会频繁抖动。修复方向：对每张图片使用 cacheWidth/cacheHeight 将解码尺寸限制到显示尺寸（例如 400×400，解码约 640KB），使 200 张图片的总解码内存可控；减小 cacheExtent 以降低预加载数量；如果图片确实需要较大显示尺寸，考虑降低 ImageCache.maximumSizeBytes 并接受更频繁的重新解码，或者使用分页/按需加载避免一次性加载过多图片。

习题9（单选）

precacheImage 的主要内存风险是：

A. 它会在磁盘上缓存图片，占用存储空间 B. 它会在 Future 完成前保持监听者，将图片钉在内存中，可能绕过 LRU 的驱逐 C. 它会强制所有图片以原始尺寸解码 D. 它会禁用 ImageCache 的 LRU 机制

参考答案：B

解读： precacheImage 的文档明确警告：“The image will remain pinned in memory at least until the caller removes its listener from the stream, even if it would not otherwise fit into the cache. Callers should be cautious about pinning large images or a large number of images in memory, as this can result in running out of memory”。A 错误：precacheImage 预取的是内存缓存，不是磁盘缓存。C 不准确：precacheImage 可以通过 ResizeImage 等 provider 限制解码尺寸，但它本身不强制原始尺寸。D 错误：它不“禁用”LRU，但 live 引用可以绕过 LRU 的驱逐。

习题10（多选）

以下哪些措施可以有效降低 ListView 中图片的峰值内存？

A. 为每张图片设置基于显示尺寸和 DPR 的 cacheWidth/cacheHeight B. 减小 cacheExtent，降低预加载的图片数量 C. 对图片设置 keepAlive: true，确保图片不会重新解码 D. 避免对列表中的大图批量调用 precacheImage

参考答案：A、B、D

解读： A 是根本性的：限制解码尺寸直接降低每张图片的内存成本。B 是正确的：更小的 cacheExtent 意味着更少的图片同时处于“已构建/已解码”状态。D 是正确的：precacheImage 会将图片钉住，增加 live 图片数量，在列表中应当避免。C 是错误的：keepAlive: true 会让图片在滚出视口后仍然被保留，增加内存占用，与“降低峰值内存”的目标相反；只有在“小尺寸、频繁滚回、重新解码成本高”的特定场景中才考虑使用。

习题11（简答）

请解释“文件大小”和“解码内存”为什么没有直接关系，并给出一个具体的数字例子。

参考答案： 文件大小是图片经过压缩（JPEG、PNG、WebP 等格式）后的字节数，它取决于压缩算法和图片内容的复杂度。解码内存是图片被展开为像素矩阵后的字节数，它取决于像素维度（宽度 × 高度）和每像素的字节数（Flutter 中为 4 字节，RGBA）。一张 4000×3000 的 JPEG 在磁盘上可能只有约 2MB（高压缩率），但解码后占用 4000 × 3000 × 4 ≈ 48MB。一张纯色的 4000×3000 PNG 在磁盘上可能只有几十 KB，解码后仍然是 48MB。文件大小和解码内存之间没有固定的换算关系；决定内存的是解码尺寸，而不是文件大小。

习题12（场景设计）

一个图片查看器页面允许用户左右滑动查看高清图片，每张图片源尺寸 3000×3000（解码约 36MB），并且使用 PageView 同时保留相邻页面的图片。当前页加上前后各一页，同时有 3 张图片 live，合计约 108MB，超过了 ImageCache 的 100MB 默认上限，但仍然发生 OOM。请分析原因并设计修复方案。

参考答案： 原因：PageView 默认会保留相邻页面（取决于 allowImplicitScrolling 和 PageView 的缓存行为），使 3 张图片同时处于 live 状态。ImageCache 的 100MB 上限只约束缓存中的非 live 条目；3 张 live 图片合计 108MB，不受 LRU 驱逐，因此可以合法地超过上限并触发 OOM。此外，每张图片的 36MB 虽然小于 100MB，但如果 ImageCache 中还有其他缓存图片，总内存会更高。修复方案：为查看器中的图片设置 cacheWidth/cacheHeight，使解码尺寸接近屏幕物理尺寸（例如 1080×2400 的屏幕，解码约 10MB/张），将 3 张 live 图片的总内存降到 30MB 左右；如果用户需要缩放查看全分辨率细节，可以在缩放时按需加载更高分辨率的版本，而不是在滑动阶段就解码全尺寸；减少 PageView 的预保留页数（如果业务允许）；在页面退出时对查看器使用的图片调用 evict，显式释放。

习题13（判断）

增大 ImageCache.maximumSizeBytes 是解决大图 OOM 的推荐首选方案。

参考答案：错误

解读： Flutter 的 breaking change 明确反对这一做法：“不再自动增大 ImageCache 的 maxByteSize 来容纳大图”，因为“这有时导致 maxByteSize 膨胀，使内存受限的系统更难工作”。迁移指南的方向是“调整图片加载逻辑，确保图片能合适地放入你选择的 maxByteSize”，而不是让缓存适应大图。增大缓存上限会延迟 OOM 的发生，但不会降低每张图片的内存成本；在低端设备上，更大的缓存反而会挤压其他内存需求。正确的首选是限制解码尺寸，让图片在较小的内存占用下能够舒适地进入缓存。

习题14（简答）

请比较 Image 的 width/height、cacheWidth/cacheHeight 和 ResizeImage 三者在图片内存管理中的角色差异。

参考答案： width/height ：布局属性，使用逻辑像素，影响图片在屏幕上的绘制尺寸和所占的布局空间。它们不改变解码尺寸，因此不直接降低内存。cacheWidth/cacheHeight ：解码属性，使用物理像素，指示引擎在解码时将图片缩小到指定尺寸。它们直接降低 ImageCache 的内存占用和解码后的像素数据量。ResizeImage ：ImageProvider 层面的包装器，与 cacheWidth/cacheHeight 是同一解码机制，适用于需要传递 ImageProvider 而不是直接构造 Image 的场景（如 DecorationImage、FadeInImage）。三者的关系是：width/height 管“画多大”，cacheWidth/cacheHeight 和 ResizeImage 管“解码多大”；内存由后者决定，视觉尺寸由前者决定。一个常见的错误是只设置前者而忽略后者，导致“画得小但内存大”。

习题15（简答）

请设计一个排查 Flutter 图片 OOM 的步骤序列，要求覆盖“计算理论内存”“区分缓存与 live”“检查动画格式”和“验证修复”四个环节。

参考答案： 第一步，计算理论内存： 对怀疑页面中的每一张图片，找到源像素尺寸，计算 宽度 × 高度 × 4 字节；乘以“同时可见数量 + cacheExtent 预加载数量 + 可能被 precacheImage 钉住的数量”。如果总和接近或超过设备图片内存预算，OOM 的风险是可计算的。第二步，区分缓存与 live： 在 DevTools Memory 视图中记录滚动前后的内存快照；检查 imageCache.currentSizeBytes（缓存字节数）和 imageCache.liveImageCount（live 图片数）。如果 liveImageCount 高，检查 precacheImage 调用和手动 ImageStreamCompleterHandle；如果 currentSizeBytes 接近 100MB，说明缓存已满，需要缩小解码尺寸或减小 cacheExtent。第三步，检查动画格式： 确认图片是否为 GIF/WebP/APNG。如果是，cacheWidth/cacheHeight 和 ResizeImage 不生效；检查源尺寸是否接近显示尺寸，如果远大于，需要服务端缩略图或减少同时可见数量。第四步，验证修复： 在低端 Android 真机上、Profile 模式下，滚动页面并观察内存曲线。修复后，理论解码内存应显著下降（通过 cacheWidth/cacheHeight 或 ResizeImage），liveImageCount 应在预期范围内（没有被意外钉住的图片），内存曲线在滚动后应能够回落到一个稳定水平，而不是持续上升。

八、本节课知识要点总结

九、下节课预告

第13课：TextStyle 重复创建坑｜样式反复实例化，不必要重绘隐患

下一课将从“图片的像素内存”转向“文本的样式对象”：TextStyle 在 Flutter 中是一个不可变的配置对象，但它的相等性比较、继承合并和重复创建会在每一帧的文本布局和绘制中产生隐性成本。你将看到：为什么在 build 中每次创建 TextStyle(fontSize: 16, color: Colors.black) 不一定导致重绘、但在某些条件下会阻止 RichText 的 RenderParagraph 复用布局结果；DefaultTextStyle 和 Theme.of(context).textTheme 如何通过 InheritedWidget 提供稳定的样式引用；TextStyle.merge 和 copyWith 在什么情况下会产生“相等但不相同”的对象；以及如何区分“样式对象被重新创建”和“文本布局被重新计算”。图片内存坑是“解码尺寸与显示尺寸失配”，TextStyle 重复创建是“样式对象的身份与内容失配”——两者都指向同一个认知：Flutter 的运行时成本由对象的实际使用方式决定，而不是由代码的视觉简洁性决定。