Flutter 实战避坑：相册页二次刷新被清空、全屏图片拉伸、ML Kit 人脸检测最小尺寸问题
摘要
本文复盘了 Flutter 相册类 App 开发中遇到的 3 个典型问题：人物页首屏正常但二次刷新后被清空、全屏图片预览时发生拉伸变形，以及 ML Kit 人脸检测偶发报错InputImage width and height should be at least 32!。文章结合实际代码，从现象、排查、根因到修复方案进行完整分析，并总结了 Flutter 状态管理、图片解码链路和端侧 AI 输入校验中的常见踩坑点。
关键词
Flutter，ML Kit，人脸检测，图片拉伸，BoxFit，状态覆盖，异步刷新，相册应用，端侧 AI，Bug 复盘
前言
最近在做 Flutter 相册类 App 时，连续遇到了 3 个很典型的小问题：
人物页首屏有内容，过一秒却被清空
图片进入全屏预览后，人物脸部被莫名拉长
ML Kit 人脸检测偶发报错：
InputImage width and height should be at least 32!
这 3 个问题看起来都不算“致命 bug”，主流程甚至还能继续跑，但它们都非常影响用户体验，也很容易长期潜伏在线上。
更关键的是，它们分别涉及：
Flutter 页面状态管理
图片解码与显示链路
端侧 AI 输入合法性校验
这篇文章就把这 3 个问题做一次完整复盘，记录现象、排查过程、根因分析以及最终修复方案，希望能给做 Flutter 相册、图片浏览和端侧 AI 应用的同学一些参考。
Bug 1：Flutter 人物页首屏正常，二次刷新后列表被清空
1. 问题现象
进入“人物”页时，页面一开始显示正常：
共 17 张图片
12 个相关标签
图片网格正常渲染
但过一秒后，页面突然变成：
0 张图片
0 个相关标签
出现空状态提示
这说明问题并不是“图片加载失败”，而是页面状态被后续一次刷新覆盖成了空结果。
2. 初步排查方向
一开始比较容易怀疑这些问题：
face cluster 索引还没准备好
有未完成照片导致 live query 查空
页面发起了两次请求，后返回的空结果覆盖了前面正确结果
这些方向都合理，但继续往下查之后发现，真正的问题比想象中更直接。
3. 根因分析
人物弹层的首屏数据和后续刷新数据，使用的不是同一套查询口径。
外层标签浏览页在构建人物簇时，取的是最近1200张照片；
但人物弹层打开后，又会通过watchLazy(fireImmediately: true)触发一次刷新，而这次刷新只查询最近800张照片。
这就导致了一个非常典型的问题：
首屏先拿到了基于
1200张数据计算出来的人物结果，所以页面一开始有图后续
fireImmediately立刻触发刷新刷新逻辑只看最近
800张如果这 17 张图不在最新 800 张里，刷新结果就变成空
UI 被空结果直接覆盖
本质上就是：
首屏和刷新使用了两套不同的数据窗口。
4. 修复方案
修复方式并不复杂，但非常关键：
将标签总览和人物弹层统一成同一个照片来源
不再出现“外层按 1200 查、弹层按 800 查”的情况
通过共享 loader，保证首屏和刷新口径一致
修复前
// 标签页 limit(1200) // 弹层刷新 limit(800)修复后
Future<List<PhotoEntity>> _loadAlbumTagBrowserSourcePhotos() { return PhotoService().isar.photoEntitys .where() .sortByTimestampDesc() .limit(1200) .findAll(); }然后让外层和弹层都走同一个入口。
5. 经验总结
这类问题的关键不在于“异步刷新”本身，而在于：
异步刷新前后，是否使用了完全一致的数据口径。
如果不是，就很容易出现这种非常迷惑的现象：
首屏有内容
一秒后没了
用户误以为数据丢失或页面异常
所以只要页面存在“首屏加载 + 自动刷新”的结构，就一定要优先检查：
前后两次查询条件是不是完全一致。
Bug 2：Flutter 全屏图片预览时被拉伸变形
1. 问题现象
缩略图看起来完全正常，但点进全屏预览后，人物脸部明显被拉长，看起来像是被强行拉成了某个固定比例。
遇到这种问题，第一反应通常会怀疑：
使用了
BoxFit.fill容器被写死了宽高比
EXIF 方向信息异常，导致宽高错乱
但这次继续排查后发现，根因并不在fit。
2. 排查过程
全屏查看器里的代码其实没有问题，用的是：
PathImage(path: path, fit: BoxFit.contain)BoxFit.contain理论上会保持原始比例，不应该产生拉伸。
既然显示层没有明显问题，那么问题就只能继续往更底层的“图片解码阶段”查。
3. 根因分析
问题出在图片组件PathImage的“智能缓存”逻辑上。
它会根据当前布局约束，同时给Image.file传入：
cacheWidthcacheHeight
如果这两个值同时被指定，Flutter 在解码阶段就可能按照这两个缓存尺寸去缩放位图。
这里有一个非常容易被忽略的点：
BoxFit.contain只负责布局阶段如何摆放图片，不会修正前面解码阶段已经发生的非等比缩放。
所以最终效果就变成了：
图片先在解码阶段被按视口宽高缩成错误比例
然后再通过
BoxFit.contain去显示表面看起来像是“显示层拉伸了”，实际上是“解码阶段就已经歪了”
4. 修复方案
对于全屏查看器，最稳妥的方式不是继续走智能缓存，而是：
保留
BoxFit.contain关闭智能缓存尺寸提示
让全屏图按原始比例解码显示
修复后代码
final image = PathImage( path: path, fit: BoxFit.contain, enableSmartCache: false, );5. 经验总结
这类问题特别容易误判成：
BoxFit.fillHero 动画变形
宽高比元数据异常
但实际上，图片解码缓存策略本身也会影响最终显示比例。
一个非常重要的经验是：
当你怀疑图片被拉伸时，不仅要检查布局层，还要检查解码层。
很多时候，问题并不是“怎么显示”，而是“图片在显示之前就已经被错误缩放”。
Bug 3：ML Kit 人脸检测报错：InputImage width and height should be at least 32
1. 问题现象
日志中偶发出现这样的报错：
PlatformException(FaceDetectorError, com.google.mlkit.common.MlKitException: InputImage width and height should be at least 32!)这段报错的意思很明确：
送进 ML Kit 人脸检测器的输入图像，宽和高至少有一边小于 32 像素。
2. 这不是“模型挂了”
这类报错特别容易让人误会成：
ML Kit 不稳定
模型加载失败
某些照片文件损坏
但这次问题本质上都不是这些，而是：
前处理阶段没有对输入尺寸做兜底。
3. 排查结果
人脸检测这条链路，并不是直接拿列表缩略图去跑检测，而是：
先根据原图生成一个辅助分析文件
再把这个文件传给
FaceDetector.processImage()
代码大致如下：
analysisFile = await _createAuxiliaryAnalysisFile(prepared.file, photo.id); final inputImage = InputImage.fromFile(analysisFile); final faces = await faceDetector.processImage(inputImage);问题在于：
这里之前没有做任何尺寸检查。
也就是说，只要某张图片本身特别小，或者某一边特别窄，就会把不满足要求的图片直接送进 ML Kit，最终抛出异常。
4. 修复方案
修复原则并不是“强行放大图片再去跑”，而是：
先读取分析图的实际尺寸
如果任一边小于 32，则直接跳过人脸检测
但不影响标签、OCR、caption 等其他 AI 分析流程
修复后逻辑
final analysisDimensions = await _readImageDimensions(analysisFile); final canRunFaceDetection = analysisDimensions != null && analysisDimensions.$1 >= 32 && analysisDimensions.$2 >= 32; final faces = canRunFaceDetection ? await faceDetector.processImage(inputImage) : const <Face>[];同时补充诊断日志，方便后续排查：
debugPrint( '跳过人脸检测 photoId=${photo.id} ' 'dbSize=${photo.width}x${photo.height} ' 'analysisSize=$sizeLabel' );5. 为什么这样处理更合理
因为这里的问题不是“整张照片都不能分析”，而只是：
这张图不适合做人脸检测。
如果因为人脸检测失败就让整条 AI 分析链路中断，就会造成更大的影响，例如：
标签结果丢失
OCR 失败
caption 缺失
数据库存储状态不完整
所以更合理的策略应该是：
人脸检测失败或不适用，只影响 face 结果，不影响整张照片的其他分析流程。
这本质上也是一种很重要的工程思路：
局部能力失败，不应该拖垮整条主链路。
这 3 个 Bug 的共同点
这次修掉的 3 个问题，虽然分别属于不同模块，但本质上都可以归类为：
口径不一致 + 边界条件未处理。
1. 页面状态口径不一致
首屏使用
1200刷新使用
800导致异步刷新覆盖正确结果
2. 图片解码口径不一致
布局层使用
contain解码层却按视口宽高同时设置了双边缓存提示
导致位图先被缩歪
3. AI 输入边界条件缺少兜底
没有检查最小输入尺寸
极端小图直接把人脸检测流程打爆
适用场景
如果你正在做下面这些项目，这篇文章里的问题都很容易遇到：
Flutter 相册或图库类应用
图片预览、缩略图、全屏查看器
本地 AI 分析链路（人脸、OCR、标签、caption）
使用 ML Kit 做端侧视觉分析
需要处理大量异步刷新和页面状态同步的 App
最后的经验
做 Flutter + 本地 AI 这类应用时，我越来越觉得，真正难的不是“把功能做出来”，而是让这些功能在各种边界条件下依然稳定。
这次的 3 个小 bug 给我的经验也很明确：
异步刷新前后一定要统一数据口径
图片显示问题不能只看
BoxFit，还要检查解码参数AI 模块的前处理一定要加输入合法性保护
很多线上问题都不是“核心逻辑完全错了”，而是：
主流程是对的，但边界没有兜住。
而工程质量，往往就体现在这些边角处。
结语
如果你也在做 Flutter 相册、图片浏览或者端侧 AI 分析相关项目，这几个坑其实都很有代表性。
看起来只是“小 bug”，但修完之后，对用户体验和系统稳定性的提升往往非常明显。
后面如果有机会，我也会继续整理这些方向的实战内容，比如：
Flutter 图片显示链路排查思路
ML Kit / OCR / Caption 协同分析设计
相册类 App 的状态流与异步刷新治理
欢迎交流，也欢迎关注后续更新。