跨平台开发 / 系统课时
安装代码生成依赖
安装代码生成依赖
Freezed 与 json_serializable 的安装关键不在包的数量,而在依赖分工。本节在 Flutter 3.47、Dart 3.13 项目中安装 Freezed 4、注解包和生成器,并用最小模型验证代码生成链路。
学习目标
- 在 Flutter 3.47、Dart 3.13 项目中安装 Freezed 4 与 JSON 代码生成依赖
- 区分 annotation 包、生成器与
build_runner的职责 - 用最小模型确认
.freezed.dart与.g.dart能正常生成
先确认 SDK 版本
先在项目根目录确认当前 Flutter 与 Dart 版本。Freezed 4 面向 Dart 3.13 这一代工具链;如果项目实际仍在更早的 SDK 上,先处理 SDK 约束,再讨论生成器版本。
flutter --version预期结果:
关键检查项:
Flutter 3.47.<PATCH>
Dart 3.13.<PATCH>补丁号、提交哈希和构建日期会随本机安装版本变化,因此不用逐字匹配整段输出,只要确认主次版本符合项目基线。
安装运行期注解与开发期生成器
在 Flutter 项目根目录执行下面的安装命令。这里显式要求 freezed 使用 4.x,其余包让 Pub 根据当前 SDK 与依赖约束选择兼容稳定版本。
flutter pub add freezed_annotation json_annotation dev:freezed:^4.0.0 dev:json_serializable dev:build_runner预期结果:
pubspec.yaml 中出现:
dependencies: freezed_annotation, json_annotation
dev_dependencies: freezed(4.x), json_serializable, build_runner
依赖解析成功,命令退出码为 0freezed_annotation 与 json_annotation 会被模型源码直接导入,因此属于普通 dependencies。freezed、json_serializable 和 build_runner 只负责开发期生成代码,不是应用业务运行时要调用的库,所以放进 dev_dependencies。

用最小模型验证生成链路
片段示例:下面是完整的 lib/models/ping.dart 模型定义,它需要生成文件才能编译。part 文件名必须与当前源文件对应,fromJson 使用箭头表达式连接 json_serializable 生成的函数。
import 'package:freezed_annotation/freezed_annotation.dart';
part 'ping.freezed.dart';
part 'ping.g.dart';
@freezed
abstract class Ping with _$Ping {
const factory Ping({
required String message,
}) = _Ping;
factory Ping.fromJson(Map<String, dynamic> json) => _$PingFromJson(json);
}在项目根目录运行生成器:
dart run build_runner build --delete-conflicting-outputs预期结果:
退出码:0
生成文件:lib/models/ping.freezed.dart
生成文件:lib/models/ping.g.dart生成成功后,不要手工编辑这两个文件。模型字段、注解或构造器发生变化时,应修改源文件并重新运行生成器,让生成结果始终由声明式模型驱动。
依赖或生成失败时怎么定位
如果安装阶段出现 version solving failed,先重新检查 flutter --version 与项目 environment.sdk,再用 flutter pub outdated 查看哪一个现有依赖限制了版本范围。不要为了“先装上”就随意降级某一个生成器,因为 Freezed、json_serializable、analyzer 与 build_runner 之间存在联动约束。
如果依赖安装成功但没有生成 .g.dart,重点检查三个位置:源文件是否包含对应 part 声明、模型是否提供 fromJson 工厂、代码生成命令是否在包含 pubspec.yaml 的项目根目录执行。遇到旧生成文件冲突时,--delete-conflicting-outputs 会清理由生成器识别出的冲突输出;如果仍失败,应先读第一条真正的错误信息,而不是只看最后一行“build failed”。
完成这一节后,项目应该形成稳定分工:模型源码与 annotation 包负责“声明想要什么”,Freezed 和 json_serializable 负责“生成什么”,build_runner 负责“何时以及按什么构建流程运行生成器”。只要这条链路能用最小模型跑通,后续复杂 JSON 模型就有可靠的生成基础。