flutter doctor 报红是因为未正确安装并配置 Flutter SDK 环境变量，而非插件问题；需下载完整 SDK、添加 flutter/bin 到 PATH、重启终端和 VSCode，并验证 which flutter 可执行。
安装 Dart 和 Flutter 插件后为什么 flutter doctor 仍报红？
VSCode 本身不提供 Dart/Flutter 运行时，插件只是编辑器增强。真正决定能否开发的是本地是否装好 SDK 并正确配置环境变量。
常见错误现象：flutter doctor 显示 Flutter (the doctor check crashed) 或提示 Command not found，即使插件已安装。
- 确认已从 官方渠道下载完整 Flutter SDK（含
dart和flutter命令），不是只装 VSCode 插件 - 将
flutter/bin路径加入系统PATH（macOS/Linux 编辑~/.zshrc或~/.bash_profile；Windows 在「系统属性 → 高级 → 环境变量」中修改） - 重启终端和 VSCode —— 插件启动时会读取当前 shell 的环境变量，仅重载窗口无效
- 在 VSCode 终端里运行
which flutter（macOS/Linux）或where flutter（Windows），确认路径可访问
VSCode 中无法识别 main.dart 或跳转到定义失效
这是 Dart 插件依赖项目根目录下的 .dart_tool 和 pubspec.yaml 来构建分析上下文。没有正确初始化项目结构，语言服务就“看不见”代码。
使用场景：新建文件夹后手动创建 main.dart，或从 Git 克隆项目但未执行 pub 获取依赖。
- 确保项目根目录有有效的
pubspec.yaml（哪怕只是空的name: my_app） - 在项目根目录运行
flutter pub get（或dart pub get），生成.dart_tool/package_config.json - VSCode 右下角状态栏应显示
Dart: Ready；若显示analyzing...卡住，可尝试命令面板（Ctrl+Shift+P）运行Dart: Restart Analysis Server - 避免在多层嵌套子文件夹中打开项目 —— 必须用 VSCode 打开包含
pubspec.yaml的那一级目录
调试时断点不命中，控制台输出全是 Waiting for connection from debug service on Chrome...</H3>
<p>这是 Flutter Web 调试的典型表现，本质是开发服务器未就绪或浏览器未正确连接调试器，和 Dart 插件配置关系不大，但容易误以为是插件问题。</p>
<p>参数差异：<code>flutter run -d chrome
默认启用调试服务，但 VSCode 的 launch 配置若指定 "webBrowser": "edge" 却没装对应扩展，就会卡住。
- 检查
.vscode/launch.json 中的 device 是否匹配你实际连接的设备（chrome / web-server / emulator-5554）
- 首次调试 Web 项目，需确保已安装 Dart Debug Extension（Chrome）或对应 Edge 扩展，并允许其访问文件 URL
- 如果用
web-server 模式，断点只在源码映射（source map）正常时生效；检查浏览器开发者工具的 Sources 面板是否加载了 main.dart 而非 main.dart.js
- Android/iOS 真机调试需开启 USB 调试并信任电脑；模拟器要确保
adb devices 能列出设备
热重载（Hot Reload）失败，提示 Performing hot reload... reloaded X of Y libraries 后无反应
.vscode/launch.json 中的 device 是否匹配你实际连接的设备（chrome / web-server / emulator-5554）web-server 模式，断点只在源码映射（source map）正常时生效；检查浏览器开发者工具的 Sources 面板是否加载了 main.dart 而非 main.dart.js
adb devices 能列出设备Performing hot reload... reloaded X of Y libraries 后无反应这不是配置问题，而是 Dart VM 对代码变更的兼容性限制。热重载只适用于局部、非结构性修改，一旦触及类签名、全局变量、main() 入口等，就必须热重启（Hot Restart）或完全重启。
性能影响：频繁热重启会清空应用内存状态，比热重载慢 3–5 秒；而盲目依赖热重载却改了不可热更的代码，会导致 UI 停滞、逻辑错乱却不报错。
- 以下修改支持热重载：
Widget build()内部逻辑、字符串文本、颜色值、State 中的局部变量 - 以下必须热重启：
class名称或继承关系变更、final字段类型改变、main()函数内容、新增/删除import行 - 按
Ctrl+\（Windows/Linux）或Cmd+\（macOS）触发热重载；Ctrl+Shift+\触发热重启 - VSCode 状态栏左下角会显示当前模式（
Hot Reload或Hot Restart），留意它是否与你的操作一致
最常被忽略的一点：Flutter 项目结构对工具链极其敏感。一个没写完的 pubspec.yaml 缩进错误，或 lib/ 下多了一层无关文件夹，都可能让分析服务器静默失败——此时没有报错，只有功能缺失。遇到异常，优先检查项目根目录的完整性，而不是调换插件版本。
