跨平台开发 / 系统课时
处理陈旧代码与生成冲突
处理陈旧代码与生成冲突
生成代码失败时,最容易浪费时间的是反复执行 build_runner,却没有确认源码、依赖和旧产物是否一致。本节给出一条从 part 声明到缓存清理的定位路径,并说明如何识别“能编译但仍在使用旧字段映射”的陈旧生成代码。
学习目标
- 按固定顺序检查
part声明、生成依赖和冲突产物 - 识别 stale generated code 导致的编译错误与旧字段映射
- 使用最小化的清理与重新生成流程恢复一致状态
先判断是源码问题还是生成物问题
以 lib/user.dart 为例,Freezed 与 json_serializable 依赖两个生成文件。文件名必须与源文件 basename 对齐,fromJson 入口也要指向正确的生成函数。
import 'package:freezed_annotation/freezed_annotation.dart';
part 'user.freezed.dart';
part 'user.g.dart';
@freezed
abstract class User with _$User {
const factory User({
required String id,
@Default('guest') String role,
}) = _User;
factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}这段源码的生效行为是:Freezed 生成不可变模型相关代码,json_serializable 生成 JSON 映射代码。验证时应同时看到 user.freezed.dart 与 user.g.dart,而不是只出现其中一个。
常见现象可以先按下面的线索归类:
| 现象 | 优先检查 |
|---|---|
Target of URI hasn't been generated |
part 文件名、生成命令是否执行成功 |
_$UserFromJson 未定义 |
fromJson 工厂、user.g.dart、json_serializable 相关依赖 |
| 生成器报告 conflicting outputs | 旧生成物或手工创建了同名文件 |
| 源码已改字段但 JSON 仍按旧名字解析 | 生成文件未刷新,或正在运行旧构建产物 |
按顺序排除生成冲突
不要一开始就删除整个项目缓存。先从最便宜的检查开始:确认 part、保存源文件、确认依赖解析正常,再执行一次允许删除冲突输出的构建。
dart run build_runner build --delete-conflicting-outputs
dart analyze预期结果
build_runner: exit code 0
dart analyze: No issues found!实际生成器日志会随版本和项目规模变化,因此应以退出码、生成文件是否刷新以及分析器是否通过为准。
如果仍然失败,再清理 build_runner 自己维护的构建图并重新生成:
dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs预期结果
build_runner: exit code 0
generated files: regenerated from current sourceclean 的目的不是“修好所有问题”,而是丢弃 build_runner 的旧构建状态。若 part 写错、注解不合法或依赖版本互不兼容,清理后仍会失败。

识别“编译通过但逻辑仍旧”的陈旧代码
陈旧生成物不一定表现为编译错误。更危险的情况是模型源码已经把字段从 user_name 改成 display_name,但运行中的应用仍使用旧 .g.dart,于是接口解析结果看起来像“后端没传值”。
定位这类问题时,不要直接修改 .g.dart 或 .freezed.dart。先比较源文件修改时间与生成文件是否同步更新,再搜索生成文件中的 JSON key 是否仍是旧值。重新生成后,执行针对该字段的解析测试,确认新映射真正生效。
依赖版本冲突要从约束关系处理
如果生成器报的是 API 不兼容、builder 无法加载或 annotation 类型不匹配,问题通常不在缓存,而在依赖约束。此时先查看解析结果,再根据报错调整 freezed、freezed_annotation、json_serializable、json_annotation 与 build_runner 的兼容版本,不要靠反复 clean 碰运气。
dart pub deps --style=compact预期结果
exit code: 0
dependency graph: resolved真正的验收标准是三件事同时成立:当前源码能重新生成、静态分析通过、关键 JSON 字段的测试按新契约通过。只看到“生成命令成功”还不足以证明陈旧逻辑已经被清除。