flutter-runtime-debugging

Flutter 运行时调试

将报告的问题转化为可重复的故障，找出第一个不正确的状态或失败边界，应用范围最小且受支持的修复，并重复相同的流程作为证据。

确定运行环境

查看 SDK 约束、构建 flavor、入口点、编译时定义、目标平台、近期变更，以及现有日志或崩溃产物。在启动另一个副本之前，先发现可用设备和正在运行的应用。如果用户选择的目标和环境与故障有关，请予以保留。

不要仅凭最后一个堆栈帧、截图或下游断言推断根本原因。记录确切的触发条件、预期结果、实际结果、构建模式、平台，以及重启后故障是否仍然存在。

如果环境提供 Dart 和 Flutter MCP 功能，请使用其检查 widget 树、结构化日志和运行时诊断；否则，使用 DevTools 和 CLI 输出获取相同证据。

有条件地加载参考资料

• 在选择目标、附加到现有进程、处理启动或生命周期故障，或缩小不稳定问题的范围时，阅读复现与附加。
• 使用 inspector、debugger、logging、network、memory、CPU 或 frame 视图验证具体假设时，阅读DevTools 诊断。

聚焦诊断

使用框架错误详情、因果堆栈、结构化日志、断点、监视项和受控状态变更。只有证据指向何处，才沿着 widget、状态、isolate、传输、插件和原生边界追踪数据及所有权。

选择修复方案前，必须确认每个相关边界上第一个不正确的状态转变。对于权限或生命周期故障，明确追踪原生回调、插件或通道的结果及错误映射、应用状态所有者，以及恢复运行或已释放的使用方。不要只列举可能原因，也不要过早决定添加防御性空值检查。

每次只更改一个相关变量。临时插桩必须有明确范围、对敏感数据进行脱敏，并在完成前移除或转换为适当的持久诊断手段。

热重载会保留状态，不能证明启动、注册、初始化、生成代码或原生配置正确。对于插件或原生注册变更，在首次调用 Dart 之前，必须针对每个受影响的受支持目标执行完整重建，并在干净进程中启动。检查启动和注册日志是否有错误，并确认不受支持的目标会按照包文档规定的行为失败，而不是意外地走到缺少插件的路径。如果重建后仍可能残留旧的原生产物或安装状态，请重新安装。

边界

• 如果任务不是诊断，flutter-device-testing 负责在具体设备上执行指定的验收流程。
• flutter-performance 负责 profile 模式跟踪和前后性能声明；仅在需要隔离功能故障或候选原因时使用运行时调试。
• flutter-testing 负责持久化的自动化测试策略；了解运行时原因后，再添加回归测试。
• flutter-observability 负责生产遥测设计和后端数据接入，但其证据可用于启动本地复现。
• 一旦确认问题涉及通道、FFI、插件、平台视图或原生生命周期代码，flutter-platform-integration 负责相应边界内的修复。

验证

在等效条件下重复原先失败的流程，然后测试最接近的错误处理和生命周期路径。在负责缺陷的层级添加范围最小且持久的回归测试。说明目标、构建模式、使用的命令或工具、观察到的证据，以及未能复现或验证的事项。

来源

• Flutter DevTools
• 调试 Flutter 应用
• 在 Flutter 中处理错误
• 调试 add-to-app
• Dart 和 Flutter MCP server