📦 第一步：核心部署 (Windows PowerShell)
| 操作 | 关键命令/操作 | 说明 |
|---|---|---|
| 1. 下载并解压 | 从 Flutter 官网 下载稳定版（如 flutter_windows_3.38.5-stable.zip），解压到无中文/空格的路径，如 D:\__install__\flutter\。 |
这是基础。 |
| 2. 永久添加Flutter到PATH (系统级) | [Environment]::SetEnvironmentVariable("Path", $env:Path + ";D:\__install__\flutter\bin", [EnvironmentVariableTarget]::Machine) |
核心命令 ，让系统在任何地方识别 flutter 命令。 |
| 3. 为当前会话立即生效 | $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User") |
必须执行，使上一步设置立刻在当前窗口生效，无需重启电脑。 |
| 4. 设置国内镜像 (永久) | [Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", "https://pub.flutter-io.cn", "User") [Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", "https://storage.flutter-io.cn", "User") |
关键步骤，解决国内网络访问问题。 |
| 5. 立即应用镜像 | $env:PUB_HOSTED_URL="https://pub.flutter-io.cn"; $env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn" |
使镜像在当前会话生效。 |
🔍 第二步：环境检查与问题诊断
核心命令 ：flutter doctor
此命令是唯一权威的诊断工具，会依次检查Flutter、Dart、Android、VS Code等。任何后续问题都应以它的输出为准。
⚙️ 第三步：按报错配置 (问题驱动)
下表是 flutter doctor 常见报错及解决命令的完整清单。
| 检查项 / 报错信息 | 根本原因 | 解决命令/操作 |
|---|---|---|
| Flutter / Dart 本身 | ||
Flutter/Dart not found |
PATH未设置或未生效。 | 重新执行第一步的第2、3条命令 ，并关闭重开终端。 |
Git fetch failure |
Git远程源为github.com。 |
在Flutter SDK目录执行： git remote set-url origin https://mirror.sjtu.edu.cn/git/flutter-sdk.git |
| Android 工具链 | ||
Unable to locate Android SDK |
1. SDK未安装。 2. 路径未告知Flutter。 | 安装 ：通过Android Studio的SDK Manager安装。 配置 ：flutter config --android-sdk "C:\Users\你的用户名\AppData\Local\Android\Sdk" |
Android sdkmanager not found |
未安装命令行工具。 | 在Android Studio的 SDK Tools 选项卡中，勾选并安装 "Android SDK Command-line Tools (latest)"。 |
Android licenses not accepted |
未接受许可证。 | flutter doctor --android-licenses (全程按y) |
| 其他平台 | ||
Chrome not found |
未安装Chrome或路径不对。 | 安装Chrome ，或设置变量： [Environment]::SetEnvironmentVariable("CHROME_EXECUTABLE", "C:\...\chrome.exe", "User") |
Visual Studio not installed |
如需开发Windows桌面应用。 | 安装 Visual Studio 2022，并勾选"使用C++的桌面开发"工作负载。 |
| 网络问题 | ||
Network resources... A network error occurred |
通常因Git引起，按上方Git问题处理。镜像变量可能未生效。 | 确保第一步第4、5条命令已执行，并重开终端。 |
🚀 第四步：环境就绪与开发命令
当 flutter doctor 显示 • No issues found!，即可开始开发。
| 类别 | 实用命令 | 说明 |
|---|---|---|
| 项目创建 | flutter create my_app |
创建名为 my_app 的新项目。 |
| 运行项目 | flutter run |
运行到默认设备（安卓模拟器或真机）。 |
flutter run -d chrome |
运行到Chrome浏览器（Web开发）。 | |
flutter run -d windows |
运行到Windows桌面。 | |
| 开发辅助 | flutter pub get |
安装项目依赖包（在项目目录执行）。 |
flutter clean |
清理构建缓存，解决一些奇怪问题。 | |
flutter upgrade |
升级Flutter SDK本身（网络需通畅）。 | |
| Dart 相关 | dart --version |
检查Dart SDK是否就绪（Dart SDK已包含在Flutter中）。 |
dart run |
运行一个纯Dart控制台程序。 | |
dart analyze |
分析Dart代码，检查潜在问题。 | |
dart format . |
格式化当前目录所有Dart代码。 | |
| 设备与构建 | flutter devices |
列出所有可用的连接设备。 |
flutter build apk |
构建Android APK安装包。 | |
flutter build web |
构建Web产物。 |
💎 核心原则与备忘
- 顺序即流程 ：严格按照 部署(PATH/镜像) -> 检查(
doctor) -> 配置(按表修复) 三步走。 - 路径是核心 ：所有命令中的路径（如
D:\__install__\flutter）必须替换为你电脑的真实路径。 - 镜像需前置 ：在中国大陆网络下，必须在执行任何
flutter命令（尤其是doctor）前设置镜像。 - 工具图形化 ：Android相关组件（SDK、命令行工具）务必使用Android Studio的SDK Manager图形界面安装，可避免95%的路径和配置错误。
- 重启终端 ：任何环境变量（PATH、镜像）修改后，最简单有效的生效方法是关闭并重新打开PowerShell窗口。
这份指南包含了从零配置到开始开发所需的全套命令和排错清单。将此作为你的部署备忘录，遇到新问题时，首先运行 flutter doctor -v（-v 查看详细日志）来定位根源，再对照上表解决即可。
