只需安装 dart sdk 即可开发 cli 工具或服务端脚本；若涉及 flutter 或 web ui，则必须使用 flutter sdk，且需正确配置 path 与 vscode 的 dart.fluttersdkpath，避免混用导致 pub get 失败、断点失效及包导入报红。
如果你只打算写 Dart CLI 工具或服务端脚本，完全不需要装 Flutter SDK；但只要涉及 UI（Flutter 或 Web），就必须用 Flutter SDK 或额外配 webdev——混用独立 Dart SDK 和 Flutter SDK 的路径会直接导致 pub get 失败、断点不命中、package:flutter/material.dart 报红。
Flutter SDK 安装与 PATH 配置必须一步到位
VSCode 的 Dart 插件不会帮你自动找 SDK，它只认环境变量里的 PATH。macOS 上常见错误是解压路径含空格或中文（如 /Users/张三/Downloads/flutter），会导致 flutter doctor 卡在 “No devices” 或报 command not found: flutter。
- 解压到纯英文路径，推荐
/Users/yourname/development/flutter - 执行
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshrc（macOS 默认 shell 是 zsh） - 运行
source ~/.zshrc后，必须验证：which flutter输出路径，flutter --version有输出，flutter doctor全绿 - Windows 用户注意：系统变量里添加的是
flutter\bin，不是flutter根目录，且重启终端才能生效
Dart 插件识别不到 SDK？检查两个关键设置
插件安装后仍显示 “Dart SDK not found”，大概率是 VSCode 没读到你配的 PATH，或者它在找错位置。不要依赖“自动检测”。
- 打开 VSCode 设置（
Cmd+,），搜索dart.sdkPath，手动填入完整路径，例如/Users/yourname/development/flutter/bin/cache/dart-sdk（macOS）或C:\src\flutter\bin\cache\dart-sdk（Windows） - 如果同时装了独立 Dart SDK 和 Flutter SDK，**务必只配置
dart.flutterSdkPath**，并删掉dart.sdkPath—— 否则插件会优先用独立 SDK，导致 Flutter 项目无法解析package:flutter/* - 确认插件启用
dart.previewLsp（设为true），否则跳转定义和类型提示会延迟或失效
真机调试前，flutter doctor -v 的红色项不能跳过
模拟器能跑 ≠ 真机能连。iOS 真机调试失败，90% 出在 Xcode 命令行工具或证书环节；Android 则多卡在 USB 调试开关、驱动或 adb devices 不识别。
- iOS：运行
xcode-select --install确保命令行工具就绪；在 Xcode → Preferences → Accounts 添加 Apple ID；设备连接后，在 Xcode 中打开ios/Runner.xcworkspace，选中设备并点击运行一次，信任开发者证书 - Android：打开手机“开发者选项”，开启“USB 调试”；在终端执行
adb devices，看到设备序列号才算通；若显示unauthorized，需在手机弹窗点“允许” - VSCode 侧边栏“Run and Debug”里选设备时，如果列表为空，别急着点“+ Add Configuration”，先关掉 VSCode，拔插设备，再重开——插件有时缓存设备状态
热重载失效？先看控制台有没有 Performing hot reload...
保存文件没反应，不是插件坏了，而是当前调试会话没走热重载通道。常见于：启动方式错误、入口文件不在 lib/main.dart、或代码里有语法硬错误卡在分析阶段。
- 必须用 VSCode 的 ▶️ 按钮或
F5启动调试（不是终端敲flutter run），否则热重载监听器不激活 - 确保修改的是
lib/下的 Widget 文件，改pubspec.yaml或android/app/src不触发热重载 - 如果控制台出现
Hot reload was rejected，说明刚改的代码有编译错误（比如少了个括号），VSCode 右下角也会弹黄标，点开看具体哪行 - 热重载（
Cmd+S）≠ 热重启（Cmd+Shift+H）：前者只刷新 UI 树，后者重建整个应用状态，别用错场景
最易被忽略的一点：VSCode 打开的必须是包含 pubspec.yaml 的**整个文件夹**，而不是单个 lib/main.dart 文件。否则插件压根不会加载 Dart 项目上下文，pub get 按钮灰掉、断点变空心、package: 导入全红——这些都不是配置问题，是工作区根本没识别成 Dart 项目。
