前阵子新同事的Mac到手第三天微信上发来一串报错截图问“哥我这Flutter环境是不是废了”我点开一看典型的Android SDK路径没找到。这场景太熟悉了——Flutter官方文档写得够清楚但真正动手配环境每一步都有坑等着你。这篇文章我就把从零开始配Flutter开发环境的完整过程重新捋一遍用的就是Mac Android Studio VS Code这套组合。整个过程不求快但求每一步都稳每一步都讲清楚“为什么这么做”下次你自己遇到问题也知道往哪儿查。1. 配置前先想清楚Flutter开发环境到底由哪几块组成1.1 一条flutter doctor命令背后的四个工具链很多人一上来就奔着“下载Flutter SDK”去结果折腾了半天flutter doctor还是红一片。先说清楚整个环境由什么组成后面才不会慌。Flutter开发环境其实由四块拼图构成Flutter SDK本身、iOS工具链、Android工具链、以及编辑器。缺了其中任何一块flutter doctor都不会给你好脸色看。Flutter SDK包含Dart运行时、Flutter框架、命令行工具。这是核心没它什么都跑不起来。iOS工具链在Mac上就是Xcode和Xcode Command Line Tools主要负责iOS模拟器、真机调试、打包。注意这套东西只对macOS有用Windows和Linux上压根儿没有这一步。Android工具链Android SDK、模拟器、JavaOpenJDK。负责Android端的一切。编辑器二选一或者两个都装Android Studio或者VS Code用来写代码、跑调试、看日志。为什么用“工具链”这个词而不用“软件”因为flutter doctor检查的并不是某个App装没装而是一整套环境变量、命令行工具、SDK组件是不是齐全。比如你装了Android Studio但没装Android SDK Command-line Toolsflutter doctor照样报错。后面我会一步步带你把每一条都验证一遍。1.2 为什么Mac上通常要装Xcode又不一定要打开它这是新手最容易疑惑的地方我不做iOS开发为什么非要装Xcode原因很简单Flutter在macOS上运行任何工具链命令都会依赖Xcode的命令行工具包括编译iOS应用、启动iOS模拟器、签名打包等。即便你只写AndroidMac上跑flutter doctor时它也会检测Xcode这一项虽然不是强制要求全部通过但如果你后面想顺手在iOS模拟器上看看效果没有Xcode就寸步难行。实际操作中我建议去Mac App Store装完整版Xcode装完打开一次让它完成初始化。这步非常重要因为Xcode首次启动会自动安装一堆附加组件不启动的话后面会有各种奇怪的权限弹窗。装完之后你大可以把它放在“应用程序”文件夹里吃灰等用到的时候再打开。1.3 网络环境是配置成败的第一道关卡在配置Flutter时网络问题比想象中更常见。因为Flutter SDK、Android SDK、Gradle依赖都需要从各种源下载如果网络不稳定经常出现下载到一半就超时的情况。国内用户可以在~/.bash_profile或者~/.zshrc里配置Flutter镜像这是官方推荐的常规操作具体配置方法我下面会写。另外Android SDK的下载在Android Studio安装时也会有一步检查网络不好就多试几次别着急。2. Flutter SDK下载与Path配置终端输命令前一定要搞懂的几件事2.1 下载哪个版本stable还是betaFlutter官网flutter.dev提供了三个渠道stable、beta、master。我的建议非常明确只用stable。虽然beta和master能提前体验新特性但开发环境最怕的是不稳定。你在网上搜到的大多数问题解决方案都是基于stable版本的出了问题好查资料。下载时注意选择flutter_macos_arm64还是flutter_macos_x64。2020年以后的Mac大部分是Apple Silicon芯片M1/M2/M3选arm64Intel芯的老款Mac选x64。如果你不确定自己的芯片型号点击左上角苹果图标 →“关于本机”里面会写“芯片 Apple M3”或“处理器 Intel Core i7”之类的信息。下载完解压后你会得到一个flutter文件夹。这里有一个非常关键的决策这个文件夹放在哪里2.2 解压目录的选择为什么建议放在用户目录下很多人的第一反应是拖进“应用程序”文件夹或者放到根目录/opt。我的建议是放在你的用户目录下比如~/development/flutter或者~/tools/flutter。原因一权限问题。如果放在系统级目录运行flutter命令时可能因为读写权限不足在安装组件、写缓存时反复弹密码框。放用户目录下就没这些破事。原因二路径好记。你不是每次都要用绝对路径放在用户目录下终端里cd ~/development/flutter就能进去配置PATH也方便。原因三多版本管理方便。比如你同时在维护老项目和新项目需要切换Flutter版本时直接在用户目录下建flutter_3.0、flutter_3.19这样的文件夹改PATH就行不用折腾系统目录。我自己就是放在~/development/flutter下的。解压完第一步先把目录结构看一眼确认里面有bin文件夹就对了。2.3 配置PATH的三种方式以及我为什么推荐.zshrcMac从Catalina开始默认shell是zsh所以你要改的是~/.zshrc文件不再是以前的~/.bash_profile。如果你用的是bash那可以同时改~/.bash_profile但现在的Mac默认就是zsh新买的机器基本不用考虑bash。打开终端执行下面命令编辑配置open -e ~/.zshrc如果文件不存在终端会提示那就先创建再打开touch ~/.zshrc open -e ~/.zshrc在文件末尾加上这一行export PATH$PATH:$HOME/development/flutter/bin注意$HOME就是当前用户的Home目录等价于/Users/你的用户名。这行意思是在原有PATH的基础上追加flutter的bin目录这样你在终端里直接输入flutter就能找到命令。保存关闭后执行source ~/.zshrc让配置立即生效。然后在终端输入flutter --version如果看到版本号信息说明Flutter SDK已经能被系统找到了。这一步就成功了。顺带说一句网上有人推荐用Homebrew安装Flutter命令是brew install --cask flutter。这种方式的好处是更新方便但坏处是版本可能不是最新的而且Homebrew本身在国内网络环境下也可能遇到安装问题。如果你已经装了Homebrew那可以尝试否则我更建议直接官网下载解压路径可控出问题也好排查。2.4 执行flutter doctor前的第一件事设置镜像在正式执行flutter doctor之前先设置Flutter的PUB镜像。这一步能帮你避开国内网络访问pub.dev超时的坑。同样是编辑~/.zshrc加上这几行export PUB_HOSTED_URLhttps://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URLhttps://storage.flutter-io.cn这两行是让Flutter的Dart包管理器和SDK下载走国内镜像速度会快很多。配置完同样执行source ~/.zshrc。然后运行flutter doctor正常情况下你会看到类似这样的输出Doctor summary (to see all details, run flutter doctor -v): [✓] Flutter (Channel stable, 3.x.x, on macOS 14.x darwin-arm64, locale zh-Hans-CN) [✓] Android toolchain - develop for Android devices (Android SDK version 34.x.x) [✓] Xcode - develop for iOS and macOS (Xcode 15.x) [✗] Chrome - develop for the web (Chrome未安装) [✓] Android Studio (version 2023.x) [✓] Connected device (1 available)打勾的项目不用管打叉的说明这一块还没配好。下面我会逐个解决。3. 用Android Studio搭起完整闭环3.1 Android Studio安装官网、版本选择与首次启动Android Studio是Google官方的IDE也是Flutter开发最完整的工具。下载地址是developer.android.com选择macOS版本注意区分Apple Silicon和Intel芯片的安装包。安装过程没什么难度——把.dmg文件拖进“应用程序”文件夹就行。真正需要注意的是首次启动时的选项如果你之前装过Android Studio它会问你“是否导入旧配置”建议选“不导入”避免配置残留。首次启动会自动下载Android SDK这个过程比较久文件有好几个G耐心等就行。网络不稳的话下载到一半可能会失败没关系重新打开Android Studio它一般会断点续传。实在不行就多试几次。启动完成后你会进入欢迎界面。先别急着创建项目去搞定SDK组件。3.2 Android SDK配置让flutter doctor的Android toolchain变绿打开Android Studio点击右下角的“Configure”或者欢迎界面左下角的“SDK Manager”。在弹出的设置窗口里确认以下几项被勾选并安装Android SDK Platform-ToolsAndroid SDK Build-ToolsAndroid SDK Command-line Tools (latest)这些是Android开发的基础工具。装完之后回到终端再跑一遍flutter doctor你会发现“Android toolchain”那一栏已经从叉变勾了至少大部分问题会被解决。如果你发现flutter doctor还是提示“Android SDK file not found: platform-tools”那说明SDK路径没被Flutter识别。大多数情况下是因为Flutter找不到Android SDK的安装位置。这时候你需要在~/.zshrc里再补一行export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/platform-tools~/Library/Android/sdk是Android Studio默认的SDK安装路径。如果没找到打开Android Studio的SDK Manager最上面会显示“Android SDK Location”复制那个路径填到ANDROID_HOME里就行。3.3 创建Android模拟器从镜像下载到启动环境配置的常见误区是Android工具链全绿了就开始写代码结果一运行发现没有设备。要让Flutter项目真正跑起来你需要一台Android虚拟设备AVD。在Android Studio欢迎界面点击“More Actions” → “Virtual Device Manager”或者叫“Device Manager”然后点“Create Virtual Device”选择一款手机型号比如Pixel 8。接着选择系统镜像新手建议选不带“Google Play”标识的版本比如API 34或API 33的普通镜像因为这些镜像调试权限更完整。最后点“Finish”完成创建。创建完成之后在设备列表里点启动按钮模拟器就会像一部独立手机一样启动。注意模拟器本身对内存占用不低如果你的Mac是8GB内存建议系统镜像选轻量一点的比如API 30以下的版本运行起来会流畅很多。3.4 安装Flutter和Dart插件让Android Studio认识Flutter项目Android Studio默认是不会识别Flutter项目的。你需要安装两个插件Flutter和Dart。打开Android Studio进入“Settings” → “Plugins”在Marketplace搜索框输入“Flutter”点击安装它会提示你同时安装Dart插件一起确认就行。装完后重启Android Studio。重启后你会看到欢迎界面多了“New Flutter Project”的选项。这说明插件生效了。3.5 用Android Studio创建并运行第一个Flutter项目点击“New Flutter Project”选择“Flutter Application”项目名称填一个比如my_first_app。这个名称会出现在Android包名里不要带大写字母否则后续的包名校验会报错。SDK路径会自动识别到你配置好的Flutter SDK位置如果没识别到手动浏览选择~/development/flutter。创建完成后项目结构会出现在左侧。初次构建Flutter项目需要下载大量Gradle依赖这个过程非常考验网络。如果卡在“Running Gradle task assembleDebug”很久通常是Gradle下载慢。解决办法是在android/目录下找到build.gradle文件修改仓库地址为国内镜像。现在Flutter的新版本已经默认加了阿里云的Gradle镜像但万一你的版本没有可以手动加上buildscript { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() } }改完保存项目会自动重新同步。看到底部进度条跑完模拟器弹出默认计数器界面你就成功迈出第一步了。4. 用VS Code实现轻量开发4.1 VS Code里只需要装两个插件Flutter和DartVS Code的定位是轻量编辑器它的优势不在项目管理而在启动速度和日常编辑体验。安装方式很多人都会但我还是提一句打开VS Code点击左侧扩展图标长得很像四个方块在搜索框输入“Flutter”找到由Dart Code团队发布的那个插件通常排在第一个点Install。安装Flutter插件时会自动装上Dart插件不需要单独装。装完之后在VS Code里按Cmd Shift P输入“Flutter: New Project”就能看到项目创建向导。这个过程比Android Studio快不少适合快速开新项目。4.2 配置Flutter SDK路径让VS Code找到它如果你在用VS Code之前已经通过命令行配置好PATH那么VS Code打开终端时是可以直接识别flutter命令的。但为了保险起见你需要设置一下VS Code的配置。打开VS Code的“Settings”Cmd ,在搜索框输入“flutter sdk”找到“Dart: Flutter SDK Path”这一项填入你Flutter SDK的绝对路径比如/Users/你的用户名/development/flutter。保存后VS Code底部的状态栏会显示Dart SDK版本和Flutter版本看到这行信息就说明配置成功。4.3 在VS Code里创建、运行和调试Flutter项目配置完之后按Cmd Shift P输入“Flutter: New Project”回车后选择项目所在目录输入项目名。VS Code会自动生成项目结构。运行项目之前你需要先启动一个模拟器或者连接真机。如果Android Studio那边已经启动了模拟器VS Code会自动检测到它。然后打开lib/main.dart文件按F5选择“Dart Flutter”调试配置项目就会开始构建。这里我强烈建议你记住VS Code的几个快捷键F5启动调试跑起来之后可以打断点。Cmd \切换热重载Hot Reload代码改动后不用重新启动直接看到效果。Cmd Shift F5热重启Hot Restart从根状态重新运行。4.4 热重载的几种触发方式以及为什么它这么好用Flutter开发最爽的就是热重载。你改了代码按一下快捷键界面几乎瞬间更新这比传统原生开发里“改代码—重新编译—启动应用”的循环快太多。有个细节需要注意热重载只对main.dart里的UI代码生效如果你改了pubspec.yaml里的依赖、或者改了原生相关配置比如Android权限、iOS的Info.plist必须手动重启项目才生效。新手经常在这上面吃亏改了依赖按热重载发现没变化还以为自己写错了。4.5 VS Code和Android Studio的分工建议用了这么久我的个人习惯是大项目用Android Studio日常开发写界面用VS Code。理由很简单Android Studio的布局预览、依赖管理、Gradle日志都更完整适合处理复杂问题VS Code胜在轻快启动快编辑体验干净写纯UI逻辑、看代码、跑测试都很舒服。两边共用同一个Flutter SDK和Android SDK切换毫无成本。如果你只是初学我更推荐先用VS Code把Dart语法练熟再去碰Android Studio那些复杂的功能面板。但有一点跑不掉模拟器管理、Android SDK配置这类基础操作迟早都要跟Android Studio打一次交道。5. 环境验证与踩坑记录flutter doctor全绿的检查清单5.1 flutter doctor全绿的“31”检查点配置完成后最后再跑一次flutter doctor。这次你需要重点看三块是否全绿FlutterSDK版本号正常没有提示“Unable to locate Dart SDK”。Android toolchainAndroid SDK路径已找到Gradle同步没问题Java版本匹配。Xcode可选但建议至少在flutter doctor里不出现红色的错误信息。Android StudioFlutter插件和Dart插件已安装VS Code插件也能被识别。如果还有打叉的地方不要慌用flutter doctor -v看详细信息里面会告诉你具体缺什么文件、哪个路径不对。5.2 Mac上常见的5个坑以及我的排查思路坑一flutter命令找不到。大概率是PATH没配好或者终端没重启。先执行echo $PATH看你的flutter路径有没有出现。没有的话就回去检查~/.zshrc。坑二Android toolchain报错提示SDK路径找不到。这个几乎都是ANDROID_HOME没设置对。去Android Studio的SDK Manager确认实际路径再回来改环境变量。坑三Gradle同步超时。这个最考验耐心。首先要确认build.gradle里有没有配镜像仓库其次要看项目根目录的gradle-wrapper.properties里Gradle版本是否跟网络下载速度匹配。新版本的Flutter已经优化了这部分遇到超时多试几次即可。坑四CocoaPods报错。这个主要出现在运行iOS项目管理依赖时。解决方案是重新安装CocoaPods然后执行pod setup。macOS 12以上版本还可能遇到Ruby版本问题需要先安装rbenv或使用系统默认Ruby 2.6注意不要乱动系统Ruby否则后患无穷。坑五模拟器启动慢、内存占用高。这不是Flutter的问题是Android模拟器本身的问题。解决办法在模拟器配置里减少分配的内存量或者直接连接真机调试真机模式反而更快。5.3 排查思路从报错信息倒推问题根源遇到Bug不要慌先做三件事看报错信息的第一行它通常会指出是哪个工具链出的问题。去终端运行flutter doctor -v它会列出每个工具的具体路径。把报错信息原样复制到搜索引擎里搜注意带上你的Flutter版本号。很多问题不止你一个人遇到网上有大量的解决方案。遇到报错先不要急着重装多数只是一个环境变量或者路径的问题。我最推荐的排查顺序是先看SDK路径 → 再看环境变量 → 再看插件版本 → 最后才考虑重装。重装是终极手段有些不熟悉环境的新手一上来就删掉所有东西重装结果反而把还好的部分弄坏了。6. 我自己的使用感受两套工具并存的工作流配置好这套环境之后我最大的感受是Flutter的命令行工具其实才是核心IDE反而只是个壳。因为无论你在Android Studio还是VS Code里操作最终都是调用了flutter命令在干活。所以如果你愿意甚至可以不用这两个IDE直接用flutter create、flutter run这种纯命令行流程开发。但显然对大多数人来说一个好用的编辑器能提升不少效率。我日常的工作流程是这样的早上到公司启动VS Code打开项目写代码。遇到需要调接口、看原生日志、甚至改Android权限的时候切换到Android Studio。模拟器用一个就够了想省内存的时候用真机。多版本Flutter需求不多但如果真遇到我推荐用fvmFlutter Version Management它是个命令行工具我之前踩了不少坑后面单独写一篇。这套环境配置好过后你如果想起本地环境有哪些问题需要我补充或者展开讲某一部分直接指出就好。