⚡ Dart Hot Reload

🔥 什么是 Hot Reload？

📊 开发体验对比

开发效率提升 10x+

🏗️ 整体架构概览

┌─────────────────────────────────────────────────────┐
│                   开发者机器                          │
│  ┌──────────────┐    ┌──────────────────────────┐  │
│  │  Dart Code   │───▶│    flutter_tools         │  │
│  │  (.dart)     │    │    (HotRunner)           │  │
│  └──────────────┘    └───────────┬──────────────┘  │
│                                  │                  │
│                      ┌───────────▼──────────────┐  │
│                      │   frontend_server        │  │
│                      │   (Kernel 编译器)         │  │
│                      └───────────┬──────────────┘  │
│                                  │ .dill           │
└──────────────────────────────────┼──────────────────┘
                                   │
                    ───────────────┼───────────────
                                   │
┌──────────────────────────────────▼──────────────────┐
│                     目标设备                          │
│  ┌──────────────┐    ┌──────────────────────────┐  │
│  │   DevFS      │◀───│   Dart VM               │  │
│  │ (虚拟文件系统) │    │   (Isolate)             │  │
│  └──────────────┘    └───────────┬──────────────┘  │
│                                  │ reassemble      │
│                      ┌───────────▼──────────────┐  │
│                      │   Flutter Framework      │  │
│                      │   (Widget Tree)          │  │
│                      └──────────────────────────┘  │
└─────────────────────────────────────────────────────┘

🔄 核心组件交互

🎯 HotRunner 核心类

源码：packages/flutter_tools/lib/src/run_hot.dart

class HotRunner extends ResidentRunner {
  final List<FlutterDevice> devices;
  final DebuggingOptions debuggingOptions;
  
  // 核心方法
  Future<int> restart({
    bool fullRestart = false,
    bool pause = false,
    String? reason,
  }) async { ... }
  
  Future<OperationResult> _reloadSources({
    required String? reason,
  }) async { ... }
}

🚀 HotRunner 启动流程

// 1. 启动应用
Future<int> attach() async {
  await _setupTerminal();
  await _connectToDevices();
  return _attach();
}

// 2. 监听文件变化
void _setupTerminal() {
  terminal.setupTerminal();
  terminal.singleCharMode = true;
  // 监听 'r' 键触发 Hot Reload
  // 监听 'R' 键触发 Hot Restart
}

// 3. 建立设备连接
Future<void> _connectToDevices() async {
  for (final device in devices) {
    await device.connect();
  }
}

👁️ 文件监听机制

Flutter Tools 通过 ProjectFileInvalidator 监听文件变化

class ProjectFileInvalidator {
  Future<InvalidatedSources> checkForChanges({
    required DateTime lastModified,
    required Uri mainFile,
    required Set<Uri> dependencies,
  }) async {
    // 检查依赖文件是否被修改
    final modifiedFiles = <Uri>[];
    for (final file in dependencies) {
      final stat = await fileSystem.stat(file);
      if (stat.modified.isAfter(lastModified)) {
        modifiedFiles.add(file);
      }
    }
    return InvalidatedSources(modifiedFiles);
  }
}

📁 ProjectFileInvalidator

// 使用示例
final result = await projectFileInvalidator.checkForChanges(
  lastModified: lastCompileTime,
  mainFile: mainFile.uri,
  dependencies: projectDependencies,
);

if (result.modified.isNotEmpty) {
  // 触发 Hot Reload
  await _reloadSources();
}

⚙️ 增量编译概述

🖥️ frontend_server

源码：pkg/frontend_server/

class FrontendServer {
  // 增量编译核心方法
  Future<CompilerOutput> recompile({
    required Uri entryPoint,
    required List<Uri> invalidatedFiles,
    required String outputPath,
  }) async {
    // 1. 解析修改的文件
    // 2. 增量更新 Kernel AST
    // 3. 生成增量 .dill 文件
    return CompilerOutput(outputPath);
  }
}

📦 Kernel 编译流程

┌──────────────┐
│  Dart Source │ (.dart 文件)
└──────┬───────┘
       │ 解析 (Parser)
┌──────▼───────┐
│  AST 节点    │ (抽象语法树)
└──────┬───────┘
       │ 类型推断
┌──────▼───────┐
│  Kernel AST  │ (类型化 AST)
└──────┬───────┘
       │ 序列化
┌──────▼───────┐
│  .dill 文件  │ (Kernel Binary)
└──────────────┘

🔧 增量编译实现

// HotRunner 中的增量编译调用
Future<CompilerOutput> _recompile() async {
  final compiler = device.generator;
  
  final output = await compiler.recompile(
    mainFile.uri,
    invalidatedFiles,  // 修改的文件列表
    outputPath: dillPath,
    packagesFilePath: packagesFilePath,
  );
  
  return output;
}

📄 .dill 文件格式

.dill 是 Kernel Binary 格式，包含编译后的 Dart 代码

📦 DevFS 概述

• 运行在 Dart VM 中
• 支持文件读写操作
• 与开发机器同步
• 存储 .dill 文件和资源文件

🏗️ DevFS 架构

┌─────────────────────────────────────────────┐
│              开发机器                        │
│  ┌────────────────────────────────────┐    │
│  │  flutter_tools                      │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │  DevFS Writer              │    │    │
│  │  └───────────┬────────────────┘    │    │
│  └──────────────┼─────────────────────┘    │
│                 │ VM Service Protocol      │
└─────────────────┼──────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│              目标设备                        │
│  ┌────────────────────────────────────┐    │
│  │  Dart VM                           │    │
│  │  ┌────────────────────────────┐    │    │
│  │  │  DevFS (虚拟文件系统)       │    │    │
│  │  │  - /main.dart.dill         │    │    │
│  │  │  - /incremental.dill       │    │    │
│  │  │  - /assets/*               │    │    │
│  │  └────────────────────────────┘    │    │
│  └────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

🔄 DevFS 同步流程

// DevFS 同步实现
Future<UpdateFSReport> _updateDevFS() async {
  // 1. 创建 DevFS (如果不存在)
  if (!device.devFS!.isCreated) {
    await device.devFS!.create();
  }
  
  // 2. 同步文件到设备
  final report = await device.devFS!.update(
    fileSystem: fileSystem,
    files: modifiedFiles,
    bundle: assetBundle,
  );
  
  return report;
}

📤 DevFS 更新实现

class DevFS {
  // 通过 VM Service 写入文件
  Future<void> writeStringFile(
    String path,
    String content,
  ) async {
    final base64Content = base64Encode(
      utf8.encode(content)
    );
    
    await vmService.writeDevFSFile(
      fsName: name,
      path: path,
      file: base64Content,
    );
  }
}

🔌 VM Service Protocol

Dart VM 提供的调试和监控协议

🔗 VM Service 连接

// 连接到 VM Service
final vmService = await vmServiceConnectUri(
  'ws://localhost:12345/ws',
);

// 获取 VM 信息
final vm = await vmService.getVM();

// 获取主 Isolate
final isolate = vm.isolates!.first;
final isolateId = isolate.id!;

🔄 reloadSources RPC

核心 RPC：reloadSources

{
  "jsonrpc": "2.0",
  "method": "reloadSources",
  "params": {
    "isolateId": "isolates/12345678",
    "force": false
  },
  "id": "req-1"
}

⚙️ reloadSources 实现

// flutter_tools 中的调用
Future<ReloadReport> _reloadSourcesInVM() async {
  final report = await device.vmService!.reloadSources(
    isolateId,
    force: false,
    pause: false,
  );
  
  if (report.success!) {
    // 重载成功
    return report;
  } else {
    // 重载失败，需要 Hot Restart
    throw HotReloadFailedException();
  }
}

📥 Kernel 加载流程

reloadSources RPC
       │
       ▼
┌──────────────────┐
│  Read DevFS      │ 读取增量 .dill
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  KernelLoader    │ 解析 Kernel
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Update Types    │ 更新类型定义
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Morph Instance  │ 实例变形
└──────────────────┘

🔄 类型更新机制

🎭 InstanceMorpher

源码：runtime/vm/kernel_loader.cc

// 实例变形核心逻辑
class InstanceMorpher {
  // 将旧类实例变形为新类实例
  void MorphInstances(
    const Class& old_class,
    const Class& new_class,
  ) {
    // 1. 遍历所有旧类实例
    // 2. 调整内存布局
    // 3. 迁移字段值
    // 4. 更新类型指针
  }
}

🎨 Widget 重建触发

VM 重载完成后，需要触发Widget 树重建

// 触发 reassemble
Future<void> _reassemble() async {
  await device.vmService!.evaluate(
    isolateId,
    'WidgetsBinding.instance.reassemble()',
  );
}

🔄 reassemble 方法

源码：packages/flutter/lib/src/widgets/binding.dart

class WidgetsBinding {
  Future<void> performReassemble() async {
    // 1. 标记所有 Element 为 dirty
    try {
      await reassemble();
    } finally {
      // 2. 触发帧调度
      scheduleWarmUpFrame();
    }
  }
  
  Future<void> reassemble() async {
    await rootElement!.reassemble();
  }
}

🌳 Element 重建流程

reassemble()
    │
    ▼
Element.reassemble()
    │
    ├─▶ State.reassemble()
    │       └─▶ 调用 setState(() {})
    │
    └─▶ Element.performRebuild()
            │
            ├─▶ Widget.build()
            │
            └─▶ Element.update()
                    │
                    └─▶ 更新 RenderObject

💾 状态保留机制

📋 状态保留规则

class _MyWidgetState extends State<MyWidget> {
  int _counter = 0;  // ✅ 保留
  
  void reassemble() {
    super.reassemble();
    // Hot Reload 时调用
    // 可在此处清理缓存
  }
  
  void initState() {
    super.initState();
    // 仅首次创建时调用
    // Hot Reload 不会调用
  }
}

🔄 Hot Restart 概述

• 销毁当前 Isolate
• 重新启动 main()
• 重新初始化所有状态
• 重新加载所有库

适用场景：Hot Reload 无法处理的修改

🔄 Hot Restart 流程

// Hot Restart 实现
Future<int> restart({bool fullRestart = true}) async {
  if (fullRestart) {
    // 1. 停止当前应用
    await stopApp();
    
    // 2. 完整编译
    final dill = await _compile(
      fullRestart: true,
    );
    
    // 3. 重新启动
    await startApp(dill);
  }
}

📊 Hot Reload vs Hot Restart

✅ 支持的操作

❌ 不支持的修改

• ❌ 修改 main() 函数
• ❌ 修改全局变量初始化
• ❌ 修改枚举类型定义
• ❌ 修改泛型类型参数
• ❌ 修改 mixin 定义
• ❌ 修改 extension 定义

⚠️ 枚举类型限制

// ❌ 不支持 Hot Reload
enum Status {
  loading,
  success,
  error,
  cancelled,  // 添加新值
}

// 原因：枚举值在编译时确定索引
// 运行时无法动态添加

⚠️ 泛型类型限制

// ❌ 不支持 Hot Reload
class MyClass<T extends num> {  // 修改泛型约束
  final T value;
  MyClass(this.value);
}

// 原因：泛型实例化在运行时已确定
// 修改约束会导致类型不兼容

⚠️ 全局变量限制

// ❌ 不支持 Hot Reload
int globalCounter = 100;  // 修改初始值

void main() {
  runApp(MyApp());
}

// 原因：全局变量初始化只在启动时执行一次
// Hot Reload 不会重新执行初始化

⚡ 性能优化

🔧 调试技巧

🔍 常见问题排查

📁 源码结构

flutter/packages/flutter_tools/
├── lib/
│   └── src/
│       ├── run_hot.dart        # HotRunner
│       ├── resident_runner.dart # 基类
│       ├── devfs.dart           # DevFS 管理
│       └── compile.dart         # 编译逻辑
│
dart-sdk/runtime/vm/
├── kernel_loader.cc             # Kernel 加载
├── object.cc                    # 对象模型
└── isolate.cc                   # Isolate 管理

📄 关键源文件

🔌 扩展与定制

// 自定义 Hot Reload 行为
class MyCustomWidget extends StatefulWidget {
  @override
  State<MyCustomWidget> createState() => _MyCustomWidgetState();
}

class _MyCustomWidgetState extends State<MyCustomWidget> {
  @override
  void reassemble() {
    super.reassemble();
    // Hot Reload 时执行
    // 清理缓存、重置状态等
  }
}

💡 最佳实践

• ✅ 频繁保存，小步修改
• ✅ 使用 StatefulWidget 管理状态
• ✅ 将复杂逻辑拆分为小方法
• ✅ 使用 const 构造函数
• ✅ 遇到问题时先尝试 Hot Restart
• ❌ 避免修改 main() 和全局变量
• ❌ 避免修改枚举和泛型约束

🐛 调试 Hot Reload

// 启用详细日志
flutter run -v

// 查看 VM Service 日志
flutter run --disable-service-auth-codes

// 连接 DevTools
flutter pub global activate devtools
flutter pub global run devtools

📝 总结

🔄 流程回顾

1. 文件监听
   └─▶ ProjectFileInvalidator 检测变化

2. 增量编译
   └─▶ frontend_server 生成增量 .dill

3. DevFS 同步
   └─▶ 通过 VM Service 传输文件

4. VM 重载
   └─▶ reloadSources RPC 加载新代码

5. 类型更新
   └─▶ InstanceMorpher 更新实例

6. Widget 重建
   └─▶ reassemble 触发重建

🎯 核心要点

📚 参考资料

• 🔗 Flutter 官方文档: flutter.dev/docs
• 🔗 Dart VM 源码: github.com/dart-lang/sdk
• 🔗 Flutter Tools 源码: github.com/flutter/flutter
• 🔗 VM Service Protocol: github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md
• 🔗 Kernel 文档: github.com/dart-lang/kernel

⚡ Happy Fluttering!