VSCode调试Dart/Flutter项目失败的根本原因是命令链中断，需先确保系统PATH正确配置dart或flutter命令，再按项目类型正确设置launch.json的type及插件路径。
VSCode 本身不运行 Dart，插件只是调用你系统里已装好的 dart 或 flutter 命令；没装 SDK、PATH 没配对、或插件路径设错，调试器就启动不了，断点全灰，pub get 报错——这些不是配置“漏了步骤”，而是命令链从底层就断了。
dart command not found 怎么快速定位
这是最常卡住的第一步。VSCode 终端或调试器报这个错，和插件是否启用无关，只说明系统找不到可执行的 dart。
- 在终端（不是 VSCode 内置终端）直接运行
dart --version：有输出 → PATH 配对了；无输出 → SDK 没装或路径没加对 - macOS/Linux 用户注意：VSCode 若非从终端启动（比如桌面图标双击），它不会继承 shell 的
PATH，必须用code命令从终端打开项目 - Windows 用户检查环境变量里添加的是
dart-sdk\bin，不是dart-sdk根目录；改完要重启所有终端和 VSCode - 别用 Flutter SDK 里的
cache/dart-sdk路径手动填进dart.sdkPath—— 这会导致纯 Dart 项目能跑，但 Flutter 项目package:flutter/*导入报红
launch.json 中 type 设 dart 还是 flutter
取决于你要运行什么代码，设错会导致断点不命中、热重载失效、甚至控制台只打印一行 “Launching…” 就结束。
- 纯 CLI 脚本（如
bin/main.dart）或服务端程序：用"type": "dart"，且"program"必须是具体文件路径，不能是目录或lib/下的模块 - Flutter 项目（含
lib/main.dart和package:flutter/*）：必须用"type": "flutter"，否则跳过引擎初始化，调试器连不上 Widget Inspector - Web 项目首次调试时，
"webBrowser": "chrome"要求已安装 Dart Debug Extension，并允许访问 file:// URL；设成"edge"却没装对应扩展，就会卡在 “Waiting for connection”
dart.flutterSdkPath 和 dart.sdkPath 到底怎么填
这两个设置互斥，填错一个就可能让整个开发流崩掉。VSCode 的 Dart 插件优先读 dart.flutterSdkPath，一旦设了，dart.sdkPath 就被忽略。
- 只开发纯 Dart CLI 工具：留空
dart.flutterSdkPath，确保dart --version可用即可；不需要装 Flutter SDK - 开发 Flutter 或 Web 项目：必须设
dart.flutterSdkPath为 Flutter 解压后的**根目录路径**（例如/Users/me/flutter或C:\src\flutter），不是bin子目录，也不是cache/dart-sdk - 如果同时装了独立 Dart SDK 和 Flutter SDK，务必删掉
dart.sdkPath设置项——插件会优先用它，导致 Flutter 项目无法解析package:flutter/material.dart - macOS 路径含空格或中文（如
/Users/张三/flutter）会导致flutter doctor卡死，必须换纯英文路径
pub get 失败、状态栏不显示 Dart SDK 版本
插件只有在识别到合法项目根时才激活语言服务。打开错目录、pubspec.yaml 缩进错误、甚至文件权限不对，都会让插件“看不见”项目。
- 必须用 VSCode 的 File → Open Folder 打开包含
pubspec.yaml的那一级目录，不是单个.dart文件，也不是子文件夹 -
pubspec.yaml至少要有name:和version:字段，且缩进必须用空格（不能用 tab） - 首次打开后，在终端运行
flutter pub get（Flutter 项目）或dart pub get（纯 Dart 项目），生成.dart_tool/package_config.json - 右下角状态栏若一直显示 “analyzing…” 卡住，按
Ctrl+Shift+P运行Dart: Restart Analysis Server
最容易被忽略的点：VSCode 启动时只读一次环境变量，改完 PATH 不重启 VSCode 是无效的；而 Flutter SDK 路径一旦设错，插件会缓存失败状态，有时得删掉 .vscode/settings.json 里的相关字段再重试。
