踩坑与问题排查记录

这是知识库里最不可替代的部分。

教程网上都有，但"我遇到了 X，原因是 Y，解法是 Z"是搜不到的。 每解决一个疑难问题，就往这里沉淀一条。

怎么用

• 遇到报错 → 直接全文搜索报错关键词（右上角搜索框）
• 按分类找 → 看下面六个分类文件
• 解决了新问题 → 按记录格式追加一条

分类

文件	覆盖	典型场景
Flutter 构建与打包	依赖、代码生成、构建失败、体积	build_runner 冲突、AAR 打不出来、包体异常
Flutter 运行时	白屏、布局溢出、状态错误、崩溃	溢出报错、setState after dispose、内存泄漏
原生与真机	权限、平台通道、真机差异、iOS/Android 特有	MissingPluginException、权限被拒、真机才复现
工具链	fvm、IDE、Git、部署脚本	版本不一致、命令卡死、构建脚本报错
前端（A 域）	部署、构建、缓存、跨域、依赖	刷新 404、静态资源 404、CORS、看不到新版
AI（G 域）	LLM API、RAG、成本、密钥	429 限流、token 超限、流式中断、维度不一致、检索差、幻觉

记录格式

每条记录固定四段，缺一不可：

## 症状描述（用报错原文，便于搜索）

**症状**
具体的报错信息或现象。要贴**原文关键词**，这样别人才能搜到。

**原因**
根因分析。不要只写"配置问题"，要写出到底哪里不对。

**解法**
可执行的步骤，带代码/命令。

**预防**
以后怎么避免再犯（检查项、规范、代码写法）。

写作要点

要点	说明
标题即搜索词	用大家真正会搜的词。"RenderFlex overflowed" 而不是"布局约束问题"
贴报错原文	报错信息进正文，才能被全文搜索命中
不写原理长文	需要理解原理时链回对应教程
标注环境	Flutter 版本、平台（Android/iOS）、是否 Release 包
一条一坑	不要把多个不相关问题塞进一条

与速查区的区别

	速查区	本区
内容	"这个怎么写"	"这个为什么出错、怎么修"
形态	代码片段	症状 + 原因 + 解法 + 预防
触发	我知道要做什么，忘了写法	我遇到了问题，不知道原因

---

待补充清单

按优先级，遇到对应问题时优先记录：

• [ ] build_runner 生成代码冲突的各类场景
• [ ] iOS 证书/描述文件的常见失败
• [ ] 混合开发（Add-to-App）集成期的构建错误
• [ ] Riverpod 状态相关的疑难 bug
• [ ] 列表/滚动的性能问题实例
• [ ] 真机与模拟器行为不一致的案例