Linux 上 Flutter 项目调试指南
一 环境准备与快速检查
- 确认环境完整：运行 flutter doctor，确保 Flutter SDK、Dart、Linux 构建工具等均为可用状态。若缺少组件按提示安装。
- 启用 Linux 桌面支持：在项目根目录执行 flutter config --enable-linux-desktop，然后获取依赖 flutter pub get。
- 运行与观察日志：使用 flutter run 启动应用；如需实时查看日志，使用 flutter logs。
- 代码质量与测试：用 flutter analyze 检查潜在问题，用 flutter test 运行单元/集成测试，提前排除逻辑错误。
二 Dart 层调试与 DevTools
- IDE 断点调试：在 VS Code 或 Android Studio 中对 Dart 代码设置断点，直接进行单步执行、观察变量、表达式求值等标准调试操作。
- 高效输出：优先使用 debugPrint() 替代 print()，避免生产构建中出现冗余输出。
- 启动 DevTools：
- 安装/启动：flutter pub global activate devtools，然后执行 flutter devtools；
- 或执行 flutter doctor --install-devtools 后，在应用运行时使用 flutter devtools attach 附加到目标设备/进程。
- 常用面板与功能：
- Flutter Inspector：查看与选择组件树，使用 Select Widget Mode、Highlight Repaints 定位布局与重绘问题；
- Performance：进行 CPU 采样/火焰图、帧时间分析；
- Memory：检测 内存泄漏、对象分配；
- Network：查看 HTTP 请求与响应详情。
三 调试 Linux 原生嵌入层 C/C++ 代码
- 前置步骤：先通过 flutter run 至少运行一次，生成必要的 CMake 链接与产物；然后退出应用。
- VS Code 配置要点：
- 安装 C/C++ 与 CMake Tools 扩展；
- 配置 c_cpp_properties.json（编译器路径、标准、IntelliSense 模式等）；
- 配置 settings.json（指向 example/linux/CMakeLists.txt 并启用打开时自动配置）；
- 配置 launch.json 两个启动项：
- Dart 启动：“type”: “dart”；
- 原生调试：“type”: “cppdbg”，将 “program” 指向构建产物，例如：“${workspaceFolder}/example/build/linux/x64/debug/bundle/your_app”（路径与可执行文件名会随项目/版本变化，请以实际构建输出为准）。
- 调试流程：先 Dart 运行一次生成产物 → 在 VS Code 选择 Debug native 配置启动 GDB/LLDB 进行原生断点调试；修改 Dart 代码后需重新 flutter run 以刷新产物再继续原生调试。
四 常见问题与实用技巧
- 启动期异常隔离：在 main() 中使用 try-catch 包裹初始化逻辑，发生错误时展示 错误页面，避免应用直接崩溃。
- 示例：
- Future main() async {
try { await myStartupLogic(); runApp(const MyApp()); }
catch (e) { runApp(const MyErrorScreen()); }
}
- 日志策略：开发阶段用 debugPrint()/dart:developer.log()；避免在生产代码中使用 print()。
- 性能优化要点：多用 const 构造函数、减少不必要的 setState、用 RepaintBoundary 降低重绘区域。
- 抓包与内嵌调试：
- 抓包：使用 Reqable 进行 API 抓包与协同调试；
- 内嵌工具：引入 flutter_ume 在应用内集成 Widget 信息、标尺、调色板、性能面板 等调试能力（仅调试构建启用）。