Flutter 异常处理

说明

• 本页记录 Flutter 开发中常见异常排查思路.
• 当前先从 shared_preferences 数据损坏导致的 FormatException 场景展开.
• 后续可继续补 UI, 网络, 状态管理和平台通道相关异常.

典型问题: shared_preferences 报错

报错示例:

FormatException: Unexpected character (at character 1)

常见原因

• shared_preferences.json 被写入了错误内容.
• 历史版本程序写入了不兼容格式.
• 程序异常退出导致持久化数据损坏.

当前处理方式

• 找到应用对应的 shared_preferences.json 文件.
• 若文件内容明显异常, 例如 NULLNULL 之类的损坏数据, 删除该文件.
• 重新打开软件, 让程序重新生成配置文件.

排查建议

1. 先确认是否是持久化数据损坏

• 看报错是否集中出现在首帧启动或读取配置阶段.
• 检查最近是否发生过版本升级或异常退出.

2. 再确认是否存在兼容性问题

• 不同版本字段结构变化时, 旧数据可能无法直接解析.
• 若使用了自定义序列化, 更要检查字段默认值和空值处理.

3. 做恢复策略

• 对高风险配置文件考虑加默认值兜底.
• 解析失败时尽量做回退, 不要让应用直接卡死在启动阶段.

使用建议

• 本页更适合作为异常排查线索页, 不替代正式日志分析.
• 真正修复时, 建议同时补数据兼容与损坏恢复逻辑.
• 若后续异常记录增多, 建议按 存储, 网络, UI, 平台通道 再拆小节.