执行flutter pub run build_runner build失败，使用json注解与序列化配置后无法理解报错

• 优先处理flutter run遗留的构建缓存冲突：
  • flutter run执行过程中生成的临时缓存、构建产物，容易和build_runner的工作目录产生文件锁、版本不匹配问题，这也是执行完flutter run后跑构建脚本失败的最高发原因
  • 依次执行flutter clean清理项目内所有历史构建产物
  • 执行flutter pub get同步当前项目所有依赖的最新版本
  • 替换原执行命令，规避旧的pub run调用方式，使用官方推荐的带冲突清理参数的构建命令：flutter pub run build_runner build --delete-conflicting-outputs

json_serializable 配置类高频报错排查 #

• 检查所有标注@JsonSerializable的实体类，是否在文件顶部正确添加了对应的part 'xxx.g.dart';声明，文件名拼写必须和实体类文件完全一致
• 核对依赖版本匹配度：json_annotation与json_serializable的版本区间需要和当前项目的Flutter SDK版本兼容，避免版本错位导致注解解析失效
• 校验实体类字段的可序列化性：枚举类型、嵌套自定义实体、特殊类型（如DateTime）需要补充对应的序列化映射配置，不能直接依赖默认解析逻辑

报错信息定位方法 #

执行命令过程中输出的日志，不要仅看末尾的失败提示，向前检索带有[SEVERE]标记的日志条目，该条目即为实际的报错根因：

• 如果提示输出文件冲突，通过前述的--delete-conflicting-outputs参数即可自动处理覆盖
• 如果提示注解或生成方法找不到，检查part文件声明、实体类构造函数配置是否符合json_serializable的要求
• 如果提示SDK版本不兼容，调整对应json_serializable的版本至适配当前SDK的区间

内容的提问来源于stack exchange，提问作者user14473358