VSCode本身不运行Dart，仅调用本地dart命令；需确保终端能执行dart --version，且VSCode通过shell环境或手动配置dart.sdkPath识别该路径，再以文件夹方式打开含合规pubspec.yaml的项目，调试时launch.json中type设为"dart"、program指向正确入口文件。
VSCode 本身不运行 Dart，它只调用你本地装好的 dart 命令；只要终端能执行 dart --version，VSCode 就大概率能跑起来——但前提是插件认得这个命令，且项目结构合规。
确认 dart 命令在终端可用，且被 VSCode 读到
这是最常卡住的起点。VSCode 的 Dart 插件不查系统 PATH，它启动时只继承你 shell 的环境变量。如果终端里 dart --version 成功，但 VSCode 状态栏右下角没显示 Dart SDK 版本，说明插件根本没拿到路径。
- macOS/Linux：检查
~/.zshrc（或~/.bash_profile）是否追加了export PATH="/path/to/dart-sdk/bin:$PATH"，然后运行source ~/.zshrc - Windows：在「系统属性 → 高级 → 环境变量」里把
dart-sdk\bin加进系统 PATH，**重启 VSCode（不是重载窗口）** - 验证方式：在 VSCode 内置终端里直接运行
which dart（macOS/Linux）或where dart（Windows），必须有输出 - 如果仍不行，打开 VSCode 设置（
Cmd + ,），搜dart.sdkPath，手动填入完整 bin 路径，例如/usr/local/share/dart-sdk/bin—— 注意是bin目录，不是dart-sdk根目录
用文件夹方式打开项目，且 pubspec.yaml 合规
VSCode 的 Dart 插件只在“打开含 pubspec.yaml 的文件夹”时才激活完整语言服务。单文件打开、路径错层、yaml 缩进用 Tab，都会导致 Dart: Get Packages 灰掉或报 Could not find a file named "pubspec.yaml"。
-
pubspec.yaml必须在项目根目录，不能藏在子文件夹里 - 最简合法结构至少含
name:和version:，且缩进只能用空格（YAML 对缩进敏感） - 示例：
name: my_cli_tool<br>version: 0.1.0<br>environment:<br> sdk: '>=3.0.0 <4.0.0'
- 右键点击
pubspec.yaml→ 选Dart: Get Packages，别在终端敲pub get—— 插件绑定的 SDK 才能生成正确的.dart_tool和分析器缓存
调试时 launch.json 的 program 字段必须写对
F5 报 Cannot open file: 'lib/main.dart'，八成是 program 路径错了。CLI 项目习惯把入口放 bin/ 下，而 VSCode 默认模板常指向 lib/main.dart。
- 确保
.vscode/launch.json中"type": "dart"（纯 Dart 项目），不是"flutter" -
"program"值必须是相对路径或绝对路径，例如"bin/main.dart"或"${workspaceFolder}/bin/main.dart" - 如果
pubspec.yaml里声明了executables:，可直接写"program": "myapp"（插件会自动映射到bin/myapp.dart） - 不要写目录名或没扩展名的文件名，
"program": "bin"或"program": "main"都会失败
运行单个 .dart 文件的快捷方式
不想建项目？可以跑单文件，但得绕过插件的项目上下文依赖。
- 最稳方式：终端里直接执行
dart run /full/path/to/script.dart—— 不走缓存，不依赖pubspec.yaml - 想用 F5：按
Ctrl+Shift+P输入Debug: Open launch.json，选 Dart 模板后修改program为脚本绝对路径，例如"${workspaceFolder}/hello.dart" - 避免用“Code Runner”之类插件运行
.dart文件——它们常绕过 SDK 版本检查，出错时连错误堆栈都截不全 - 注意语法：如果用了
void main() async {，就得import 'dart:async';，否则dart run直接退出，F5 也卡住无响应
容易被忽略的是：VSCode 启动时只读一次环境变量，改完 PATH 必须彻底重启；而 dart.sdkPath 和 dart.flutterSdkPath 不能共存，混配会导致 Flutter 项目找不到 package:flutter/* —— 这类路径冲突不会报错，只会静默失效。
