1. 先建立整体认知跑 Flutter 项目到底需要哪几块拼图我见过太多人网上搜教程装到一半就卡住Flutter 装了VS Code 装了结果flutter doctor一片红不是缺 Android SDK就是找不到 Visual Studio toolchain。其实问题不在于步骤复杂而是大家没搞明白这套环境由哪几块组成。先把结论放在前面你要让 Flutter 项目在 Windows 上跑起来至少要准备三样东西。第一样是 Flutter SDK 本身它负责提供flutter命令、Dart 运行时以及一套跨平台 UI 框架。第二样是 Android SDK它负责把 Flutter 代码编译成 Android 应用如果你只想跑 Windows 桌面版或者 Chrome 网页版Android SDK 可以暂时不装但只要你碰 Android就得有它。第三样是 VS Code这是你的编辑器和调试器配合 Dart、Flutter 两个扩展之后才能做到“写完代码一键运行”。我这里强调一下很多人会把 VS Code 和 Visual Studio 搞混。VS Code 是轻量编辑器Visual Studio 是微软的完整 IDE。Flutter 如果要编译 Windows 桌面应用依赖的是后者不是前者。这个坑我后面专门用一节来展开因为它的报错信息“unable to find suitable visual studio toolchain”吓退过无数新手。至于为什么推荐 VS Code 而不是 Android Studio我的理由很简单VS Code 打开快内存占用小插件生态丰富写 Dart 代码的体验非常轻快。Android Studio 当然功能更全但它本质上是 IntelliJ IDEA 套了个 Android 壳对新机器不够友好。如果你只是做 Flutter 开发VS Code 完全够用而且后续可以用命令行工具把 Android SDK 也搞定不一定非要装 Android Studio。下面我会按照我日常配环境时的顺序一步步带你把 Flutter Android SDK VS Code 装好中间每个“为什么这么做”我都会解释而不是只给你复制粘贴的命令。2. 动手前先解决三个最容易被忽略的前置项2.1 磁盘空间和目录规划别看安装的时候好像只是解压几个压缩包等你flutter run跑第一次项目Gradle 会下载一堆依赖Android SDK 也会缓存各种编译工具。我建议你至少预留 10GB 到 15GB 的空间。安装路径一定要提前想好。我的习惯是建两个独立目录Flutter SDK 放在D:\flutterAndroid SDK 放在D:\Android\Sdk这两个目录最好都放在非系统盘。原因有两个一是系统盘 C 盘默认权限严格有些解压工具写入时会出问题二是 Flutter 项目编译时会产生大量临时文件放在机械硬盘或者空间紧张的 C 盘会影响构建速度。2.2 JDK 版本不是随便装一个就行Android 编译链路离不开 Java。Flutter 官方虽然不在第一步强制要求你装 JDK但当你执行flutter doctor时如果检测不到合适的 Java 环境Android toolchain 就会标红。我推荐的版本是 JDK 17别用 JDK 8也别盲目追新用 JDK 21 或更高版本。原因很简单新版 Android Gradle PluginAGP和 Gradle 版本对 JDK 有明确兼容范围JDK 17 在 Flutter 3 系和 AGP 8.x 这条主线上是经过验证的稳妥组合。安装 JDK 后要配置JAVA_HOME环境变量。在 Windows 搜索框里输入“环境变量”打开“编辑系统环境变量”然后在“系统变量”里新建JAVA_HOMEC:\Program Files\Java\jdk-17接着编辑Path在末尾追加一行%JAVA_HOME%\bin配置完成后打开一个新的 cmd 窗口输入java -version能打印出 17 版本信息就算成功。这一步卡住的人很多大多数是因为配置完后没有新开终端Windows 不会自动刷新环境变量。如果你不想自己下载 JDK也可以安装 Android Studio让它自动携带一个 JBRJetBrains Runtime。但从我个人的使用习惯来说我更喜欢显式控制JAVA_HOME这样命令行工具和 VS Code 都能复用同一个 JDK排错时不会出现“为什么终端能编译、IDE 里却不行”这种诡异问题。2.3 开启 Windows 开发者模式这步非常容易忽略但 Flutter 官方环境检查里明确会检查。Windows 的开发者模式允许系统创建符号链接Flutter 的某些插件机制会用到这个能力。打开方式Windows 设置 - 隐私和安全性 - 开发者选项 - 打开“开发人员模式”。开启之后建议重启一次电脑确保系统服务生效。如果你到这里就跳过了后续flutter doctor可能会提示Flutter requires a Windows developer mode enabled虽然不一定会立刻报错但调试某些插件时会莫名失败。3. Flutter SDK 下载与配置版本选择、解压路径、环境变量3.1 从哪里下载、下载哪个版本Flutter 官方下载页面是https://docs.flutter.dev/release/archive你会看到 Stable、Beta、Master 三列。我的建议非常明确永远先用 Stable。Beta 和 Master 能提前体验新特性但新项目刚创建就遇到 bug 的概率也高。你是来写应用的不是来给 Flutter 团队当测试员的。页面上的最新的 Stable 版本直接下载 Windows 版的 zip 压缩包即可。下载完解压后建议把解压得到的flutter文件夹整个移动到D:\flutter。注意不要让最终路径变成D:\flutter\flutter\bin最理想的路径结构是D:\flutter\bin\flutter.bat。3.2 解压路径为什么这么讲究很多人觉得路径随便放其实这里全是眼泪。如果路径里有中文比如D:\开发工具\flutterFlutter 的 Gradle 脚本在读取路径时容易出现编码问题如果路径里有空格比如C:\Program Files\flutterAndroid 构建工具在解析命令行参数时也可能被空格打断。遇到这种问题查错查到半夜才发现是路径搞的鬼真的得不偿失。所以我强烈建议你在动手前就把目录规划好别等到flutter doctor报错再搬家。虽然重新解压一次好像不复杂但如果你已经创建了多个项目它们在android/local.properties里记录的是绝对路径路径一变所有项目都得重新配置。3.3 配置环境变量与 flutter doctor 验证配置完路径后需要把D:\flutter\bin添加到系统Path里。然后执行环境变量的刷新也就是新开一个 cmd 窗口输入flutter --version如果第一次执行时提示Waiting for another flutter command to release the startup lock别慌等几秒再执行一次。这是因为 Flutter 首次运行要初始化一些缓存文件多个命令同时进来时会启动一个锁机制。接下来是关键验证步骤flutter doctor这个命令会检查 Flutter 依赖的各条工具链是否就绪。第一次运行时大概率会发现Android toolchain 显示红叉因为 Android SDK 还没装Visual Studio 显示红叉因为你还没装 Visual StudioVS Code 显示绿勾说明 Flutter 已经能识别到编辑器这些都是正常现象不需要立刻去解决。你现在只需要确认 Flutter 本身那一行是绿色即可。真正的战斗从下一步开始。4. Android SDK 安装不用 Android Studio 也能装但版本要对4.1 到底需不需要 Android Studio网上很多教程会让你直接装 Android Studio因为它自带 SDK Manager界面操作确实方便。但我的路线更精简如果你主要是用 VS Code 写 Flutter完全可以只装 Android SDK 的命令行工具。这样能省下 Android Studio 那好几个 GB 的空间内存压力也小很多。不过这里有个前提你之后要跑 Android 模拟器的话模拟器本身需要用 AVDAndroid Virtual Device来创建和管理。Android Studio 在创建 AVD 这件事上确实比命令行方便。我的实际做法是主开发环境用 VS Code 命令行 SDK同时安装一个 Android Studio 只用来建模拟器创建完 AVD 后平时不打开它。这样既不用担心缺省工具也能让日常开发保持轻量。4.2 命令行安装 SDK 的具体步骤先去 Android 开发者官网下载 Command line tools也就是commandlinetools-win-latest.zip。这个文件不大几十 MB 左右。解压后你会发现里面是一个cmdline-tools文件夹里面只有一个bin目录。这里有个非常关键的坑你不能直接把整个文件夹扔进 SDK 目录就完事必须按下面的层级摆放D:\Android\Sdk\cmdline-tools\latest\bin\sdkmanager.bat也就是说解压得到的bin目录外面的那层文件夹需要改名为latest然后放到cmdline-tools目录下。这个结构是sdkmanager识别版本的必要条件很多人在这一步栽跟头结果终端敲sdkmanager一直提示找不到组件。路径就绪后设置两个环境变量ANDROID_HOMED:\Android\Sdk然后在Path中添加%ANDROID_HOME%\platform-tools %ANDROID_HOME%\cmdline-tools\latest\bin接下来用管理员身份打开一个新的 cmd先跑一遍sdkmanager --list如果这个命令能正常列出大量 SDK 包说明命令行工具安装成功。然后接受许可sdkmanager --licenses运行时会连续弹出很多条Accept? (y/N)直接按住 y 回车直到回到命令行提示符。这一步不能偷懒不接受许可证的话后面flutter doctor会一直提示Android license status unknown。最后安装实际编译需要的组件sdkmanager platform-tools platforms;android-35 build-tools;35.0.0这里我特意用 Android 35 举例因为它目前是稳定性和兼容性都比较好的一条版本线。如果你当前下载的 Flutter SDK 版本更新项目默认compileSdk可能会是 36 或更高那时可以在sdkmanager --list里搜到对应版本再补装。原则就是让已安装的 SDK Platform 版本号大于或等于项目里声明的compileSdk但没必要追求最新因为最新预览版反而可能带来 Gradle 解析错误。4.3 使用 Android Studio 的可视化安装方式如果你还是想用 Android Studio 来管 SDK那流程更简单在 Android Studio 的欢迎界面选择“More Actions”-“SDK Manager”然后勾选以下组件Android SDK Platform 35Android SDK Build-Tools 35Android SDK Platform-ToolsAndroid SDK Command-line Tools安装后 Android Studio 会自动把 SDK 放在C:\Users\你的用户名\AppData\Local\Android\Sdk。你需要在系统环境变量里把ANDROID_HOME指到这个路径。这个路径没有中文和空格但是藏得比较深后续如果用命令行跑adb一定要把%ANDROID_HOME%\platform-tools加入Path。装完后重新执行一次flutter doctor正常的输出里Android toolchain - develop for Android devices这一行应该是绿色并且会显示当前识别到的 SDK 版本。如果还提示cmdline-tools component is missing十有八九是 4.2 里我说的latest目录层级问题。5. VS Code 侧配置扩展、设备选择、启动配置5.1 必装扩展与实际作用打开 VS Code在扩展面板里搜索下面三个扩展并安装DartFlutterAndroid iOS Emulator可选但能让你在编辑器里快捷启动模拟器先说 Dart 和 Flutter 的分工。Flutter 扩展会调用你安装的 Flutter SDK负责代码补全、热重载、调试器等核心功能Dart 扩展则负责 Dart 语言的语法高亮、静态分析和调试协议。两个一起装才能形成一个完整的开发闭环。安装完后你可以在 VS Code 的命令面板CtrlShiftP里输入Flutter: DoctorVS Code 会直接帮你跑一次环境检查结果会以输出面板的形式展示。这个功能比自己去终端输入命令更直观一点也更适合新手定位问题。5.2 设备选择Android 模拟器、Windows 桌面还是 ChromeVS Code 底部状态栏会有一个“No Device”字样点击它可以看到当前可用的设备列表。这个列表依赖两个条件一是你要运行的平台工具链已经安装二是当前有可用的设备。如果你选择了 Android 真机调试需要先在手机上开启“开发者选项”和“USB 调试”。用数据线连上电脑后在终端输入adb devices如果看到设备但状态是unauthorized那是手机弹窗授权你没有点“允许”。如果完全看不到设备大概率是驱动问题或数据线不支持数据传输换一根原装线试一下。如果你没有真机也没有模拟器又想先看到界面可以先选 Chrome。只要项目里包含 Web 平台支持flutter run -d chrome就能让你用浏览器预览 Flutter 页面。初学者完全可以先把开发重心放在逻辑和 UI 上等要测试 Android 能力了再捣鼓模拟器。如果你想在 Windows 桌面上直接运行那么会触发前面多次提到的 Visual Studio 问题。后面第七节我会详细讲怎么装。5.3 建议加到 settings.json 里的配置VS Code 虽然开箱即用但有几个配置能减少日常摩擦。打开设置后搜索“json”选择“在 settings.json 中编辑”加入下面的内容{ dart.flutterSdkPath: D:\\flutter, [dart]: { editor.formatOnSave: true } }dart.flutterSdkPath的作用是告诉 VS Code 用哪个 Flutter SDK。如果你系统Path里已经配好了这个字段可以省略。但如果你电脑上有多个 Flutter 版本比如用 FVM 做多版本管理这个字段就必须非常小心它是绝对的路径切版本时需要同步改回来否则 VS Code 会一直调用旧版 SDK给你一种“明明换了版本却不起作用”的错觉。6. 从创建项目到跑起来完整命令和踩坑点6.1 用 flutter create 创建项目先找一个干净的代码目录例如D:\projects然后打开终端cd D:\projects flutter create my_app cd my_app执行成功后会生成一个包含完整目录结构的项目。这里有几个命令细节你可能会在网上的旧教程里看到不同写法flutter create my_app会创建所有支持平台的目录包括android/、ios/、web/、macos/、windows/、linux/。flutter create -e my_app会生成一个空的示例工程代码更干净但少了默认的计数器 demo。项目名必须是小写字母加下划线不能有大写字母、空格或连字符。比如my_app合法MyApp不合法my-app在 Android 模块命名上会非常别扭。创建完项目后先跑一下依赖flutter pub get如果网络环境正常这个命令应该在十几秒内结束。如果卡了很久通常是在拉取 Pub 远程仓库的依赖可以检查一下本机网络策略但这不是本文要讨论的范围。6.2 在 VS Code 里运行项目用 VS Code 打开刚才生成的D:\projects\my_app文件夹。打开后点击侧边栏的“运行和调试”或直接按F5然后选择Dart Flutter。如果你已经在底部状态栏选好设备比如“Windows”或“Chrome”VS Code 会直接编译并启动如果没选设备它会让你从设备列表里挑一个。第一次运行会非常慢尤其是 Android 项目Gradle 需要下载 wrapper、依赖插件、构建工具链。这个过程可能长达几分钟甚至更久很多人以为电脑卡死了其实不是。你可以在终端面板看到类似Running Gradle task assembleDebug...的提示。这里分享一个判断技巧第一次慢是正常的但如果你观察到同一行日志卡了超过 15 分钟都没有变化那大概率不是单纯在下载而是某个依赖源访问不通。可以按CtrlC中断重新执行flutter pub get或者检查项目里 Gradle 仓库地址是否有需要调整的地方。6.3 项目目录结构和后续调整运行成功后你会看到一个默认的 Flutter 计数器页面点按钮数字会加一。这个过程能跑通说明环境已经完备。接下来认识一下几个关键文件lib/main.dart是应用入口和页面源码你 99% 的日常写代码都在lib目录下完成。pubspec.yaml是依赖清单类似 Android 里的build.gradle和前端里的package.json。android/app/build.gradle是 Android 构建配置比如compileSdk、minSdk、targetSdk版本。android/local.properties里记录了本机 SDK 路径如果你把 Android SDK 移动了位置要来这里同步。我自己的习惯是每次新建项目都先打开android/app/build.gradle看一次版本号因为 Flutter SDK 升级后新模板默认的compileSdk可能跟我本机装的 SDK 版本不一致提前把版本对齐能省掉很多报错。7. 四个高频报错的完整排查思路7.1 “unable to find suitable visual studio toolchain” 怎么处理这个报错是标题热搜词里出现次数最多的一个几乎可以判断为“Windows 桌面运行”的第一大坑。先记住一个反直觉的结论报错的元凶不是 VS Code而是你缺少 Visual Studio。Flutter 在编译 Windows 原生插件时需要调用 MSVC 编译器和 Windows SDK这些东西只有完整的 Visual Studio 才带。你有一个配置得很完美的 VS Code 完全没用因为 VS Code 只是个编辑器不带编译器。解决办法去 Visual Studio 官网下载 Community 版本。安装时在“工作负载”里勾选“使用 C 的桌面开发”。右侧确保勾选了 Windows 11 SDK 或 Windows 10 SDK。安装完成后重启电脑。之后重新运行flutter doctor如果看到Visual Studio - develop Windows apps这一行变绿就可以执行flutter run -d windows了。这个报错最迷惑人的地方在于你明明安装了 VS Code名字也很接近但 Flutter 找的是另一个东西。所以以后再看到 “Visual Studio toolchain”第一反应应该是去检查真正的 Visual Studio而不是检查 VS Code 插件。7.2 Gradle 报错You are applying Flutters main Gradle plugin imperatively using the apply script这个报错多发生在旧项目升级 Flutter 版本之后报错原文大概是You are applying Flutters main Gradle plugin imperatively using the apply script method, which is no longer supported.意思是新版本的 Flutter Gradle 插件要求你使用 plugins DSL 的方式声明插件但你的项目还在用老的apply from脚本方式。这个改动发生在 Flutter 模板切换配置策略之后老项目不会自动迁移。解决方案是改两个文件。先看android/settings.gradle把它替换成类似这样的内容plugins { id dev.flutter.flutter-plugin-loader version 1.0.0 id com.android.application version 8.3.0 apply false id org.jetbrains.kotlin.android version 1.9.24 apply false }然后再看android/app/build.gradle把文件顶部的旧插件配置改成plugins { id com.android.application id kotlin-android id dev.flutter.flutter-gradle-plugin }这里有几个版本号要特别注意com.android.application和org.jetbrains.kotlin.android的版本应该和你的 Gradle、JDK 兼容。上面给的是我实测过的一组配对如果你用更新的 Flutter 版本可以用flutter create temp_project临时创建一个新工程然后去它的settings.gradle里复制版本号这是最稳妥的做法。改完之后执行flutter clean flutter pub get flutter run如果你在改完settings.gradle后还看到各种“no such property”之类的错误可以先检查有没有同时存在apply plugin旧语法新旧混用会让 Gradle 进入一种很混乱的状态。整个文件只保留 plugins DSL不要两边都写。7.3 Android SDK 路径和版本不匹配类报错这类报错形式多样但根因就两个路径没配对或者版本不够。比如flutter doctor显示Android toolchain - develop for Android devices (Android SDK version 37.0.0)同时下方一堆cmdline-tools component is missing这说明你的 SDK 里有新的平台版本但命令行工具路径不对。先去检查ANDROID_HOME指向的目录下有没有cmdline-tools\latest\bin。如果没有回到 4.2 节把目录结构重新整理一遍。还有一类报错是项目构建时说compileSdk 35 requires Android SDK 35这种最简单用sdkmanager --list | findstr platform找到你的目标版本然后安装即可sdkmanager platforms;android-35另外提醒一句如果你本机装了多个 SDK 版本尽量不要在local.properties里手动硬编码路径因为它很容易在你换项目后出现“这个项目能编译、另一个项目找不到 SDK”的怪问题。让 Flutter 自己去读ANDROID_HOME全局变量才是统一且省心的做法。7.4 设备连不上或模拟器启动失败如果你选择了 Android 模拟器但启动后 VS Code 状态栏依然显示 “No Device”第一步先检查你自己的 AVD 是否存在。在终端输入emulator -list-avds如果列表为空说明你还没创建虚拟设备。最快的方式是用 Android Studio 的 Device Manager 点几个按钮创建命令行方式也可以但要先安装 emulator 组件和系统镜像比如sdkmanager emulator system-images;android-35;google_apis;x86_64 avdmanager create avd -n pixel_6 -k system-images;android-35;google_apis;x86_64 -d pixel_6启动时如果模拟器黑屏或秒退常见原因有“Windows 虚拟机监控程序平台”没开启、电脑 BIOS 虚拟化没打开、系统镜像和 CPU 架构不匹配。Windows 上优先选x86_64镜像不要选arm64镜像否则性能和兼容性都很差。真机调试的问题一般集中在驱动和数据线。我遇到过最奇怪的一次是手机能显示充电但adb devices永远空列表。最后换了一根支持数据传输的线立刻解决。所以如果你在其他电脑上能连、换台电脑就失联优先排查线和 USB 模式别急着重装驱动。8. 装完之后我建议你做的几件事环境跑通只是起点但很多人跑通之后反而不知道下一步干什么。我给几条基于实际经验的建议。第一保存一份flutter doctor -v的完整输出。这个文件在你以后遇到任何环境问题时有非常大的参考价值它能一目了然地展示 Flutter 识别到的每条工具链版本。别等到环境崩了再想恢复现场那时候你可能连当初装了哪个版本都说不清。第二如果你打算同时维护多个 Flutter 项目并且每个项目锁定的 Flutter 版本不一样趁早接触 FVMFlutter Version Management。它本质上是一个 Flutter 多版本管理工具能让你在不同项目之间切换版本。命令很简单fvm install 3.22.0 fvm use 3.22.0 fvm flutter run虽然它增加了学习成本但当你真的被“这个旧项目必须用旧版 Flutter 才能编译”卡住时就会感谢当初装了 FVM。第三刚开始接触 Flutter别急着追求一上来就做出完整 App。先把手里的默认计数器项目拆开看理解main.dart里的runApp是什么、build方法为什么会被反复调用、热重载和热重启的区别是什么。把这些基础概念吃透远比盲目抄十几个 UI 模板更有价值。最后说一个我个人的小习惯每次新建一个 Flutter 项目我会先在android/app/build.gradle里看一眼compileSdk、minSdk、targetSdk这三个值再把local.properties的 SDK 路径确认一遍。这两处是 Android 构建时最容易出幺蛾子的地方提前确认能让后续的每一次flutter run都稳如老狗。