说实话我第一次在 Windows 上配 Flutter 环境时被这个报错卡了整整一个下午。flutter doctor前几项全绿唯独 Android licenses 后面挂着[!] Android license status unknown于是我按提示执行flutter doctor --android-licenses等来的不是交互式的授权确认而是一行冷冰冰的Exception in thread main java.lang.RuntimeException: Android sdkmanager tool was found but failed to run.相信搜索到这篇文章的你大概率和我当时一样不知道到底是谁没装、谁配错了、谁版本不对。别急这篇不是数据库式的“复制粘贴答案”而是带你把整个链路拆开理解这个报错为什么会出现、怎么定位真正原因以及最终怎么把它彻底解决。1. 这条报错到底意味着什么拆开 flutter doctor 的调用链路1.1 flutter doctor 与 Android 许可证检查的关系先理清一个基本问题flutter doctor怎么知道 Android 许可协议尚未接受Flutter 自身不做 Android 打包它需要借助 Android SDK 里的命令行工具来完成真实任务。当flutter doctor发现你的 Flutter 项目需要验证 Android SDK licenses 时它会做这么几件事使用你预先配置的ANDROID_HOME或ANDROID_SDK_ROOT环境变量找到 Android SDK 安装根目录在这个根目录下的cmdline-tools文件夹里寻找sdkmanager可执行文件调用sdkmanager --licenses把用户需要接受的所有许可协议打印出来读取交互式输入把“接受”结果写回本地的~/.android/licenses目录。也就是说flutter doctor --android-licenses只是一个壳真正的干活工具是sdkmanager。如果sdkmanager本身启动失败Flutter 拿不到任何有用反馈仅能从进程退出状态推断这个工具“找到了但没跑起来”。1.2 “was found but failed to run” 的准确含义这个报错信息在 Flutter 源码里实际上是一个兜底异常。它的字面意思非常明确was foundFlutter 已经在 Android SDK 目录里找到了sdkmanager的可执行文件所以“没有安装 Android SDK”不是问题的原因failed to run找到了文件但执行它时进程崩溃、超时或者立刻以非零状态退出。听起来很简单但问题恰恰出在“为什么没跑起来”。我在实际排查中见过至少四类触发条件它们的现象都是这一条 RuntimeException底层原因却完全不同触发条件底层真实现象缺少 cmdline-tools 组件找不到sdkmanager.bat或对应 shell 脚本Java 版本太旧UnsupportedClassVersionError或NoSuchMethodErrorJAVA_HOME 未设置或指向错误启动 JVM 失败提示找不到 Java目录权限或路径含特殊字符无法创建临时文件或运行权限不足所以正确排除思路不是“见到这个报错就去重装 Android Studio”而是先搞清楚当前机器上究竟是哪一类问题。1.3 为什么真实异常会被吞掉你可能已经注意到报错只有一行完全看不到 Java 内部异常的堆栈信息。这是因为 Flutter 在调用外部命令时并不会无条件把子进程的标准输出和标准错误原样透传给你。它默认只显示自己封装好的消息真正的sdkmanager输出被丢到了日志里。这有点像甲方给你打电话说“方案不行”但不告诉你哪一页不行也不把对方修改意见转给你。如果只看最终提示你只能知道方案挂了具体挂在哪一步只能自己去查。我自己排查时找到被吞掉的详细输出方法是直接手动执行sdkmanager也就是下一节要讲的关键操作。2. 挖出真报错手动执行 sdkmanager既然 Flutter 不把细节告诉我们那就绕过 Flutter直接敲命令。手动运行sdkmanager有两个好处一是能看到真正的 Java 异常堆栈二是能确认是不是环境配置问题。这也是我推荐每个被这问题困扰的开发者先做的一步。2.1 先确认你的 Android SDK 到底放在哪执行下面的命令先看 Flutter 认为你的 SDK 在哪个目录flutter doctor -v输出里有一行类似[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0) • Android SDK at C:\Android\sdk • Platform android-34, build-tools 34.0.0 • Java binary at: C:\Program Files\Android\Android Studio\jbr\bin\java • Java version OpenJDK Runtime Environment (build 17.0.x)其中Android SDK at后面的路径就是关键。如果这里没打印路径说明ANDROID_HOME环境变量没设置好Flutter 根本找不到 SDK那又是另一个故事了。也可以手动检查环境变量Windows CMDecho %ANDROID_HOME% echo %ANDROID_SDK_ROOT%PowerShellecho $env:ANDROID_HOME echo $env:ANDROID_SDK_ROOTmacOS / Linuxecho $ANDROID_HOME echo $ANDROID_SDK_ROOT两个变量都为空也没关系Flutter 还能通过 Android Studio 配置来发现 SDK 位置不过既然报错已经走到sdkmanager was found至少说明 SDK 本身是能被找到的。2.2 打开 cmdline-tools 目录看结构拿到 SDK 根目录后打开它重点看cmdline-tools文件夹。像我见过比较典型的目录结构如下C:\Android\sdk ├── build-tools ├── cmdline-tools │ ├── 11.0 │ ├── latest │ └── tools ├── emulator ├── platform-tools └── platforms这里有几个关键点latest目录是新版 Android Studio 安装命令行工具的默认位置里面结构为latest/bin/sdkmanager.battools目录是旧版 Android SDK Tools 的遗留位置老版本 Flutter 很偏爱它带版本号的目录如11.0通常是你手动解压命令行工具时留下的。Flutter 在找 sdkmanager 时优先级在不同版本里略有差异但原则上是“先找cmdline-tools/tools/bin/sdkmanager再找cmdline-tools/latest/bin/sdkmanager”。如果你的目录结构是cmdline-tools/11.0而没有latest或toolsFlutter 就会认为“没有找到可用的 sdkmanager”报错文案会变成 not found 而不是 failed to run。这里我是建议你顺手把cmdline-tools目录完整列出来留个截图或者记录下来后面修复会用到。2.3 检查 Java别只信 java -versionsdkmanager本质上是一个 Java 程序所以 Java 环境对不对至关重要。注意光在终端敲java -version能看到版本还不够因为那只能说明 PATH 里的 java 能用不代表 Flutter 和 sdkmanager 用的也是同一个。最可靠的检查方式Windows CMDecho %JAVA_HOME% %JAVA_HOME%\bin\java.exe -versionmacOS / Linuxecho $JAVA_HOME $JAVA_HOME/bin/java -version如果 JAVA_HOME 为空或者指向的目录里根本没有bin/java那sdkmanager启动 JVM 时就会失败。尤其是很多人电脑上装了一堆 JDK 版本Oracle JDK 8、OpenJDK 11、Android Studio 自带的 JBR 17环境变量一乱问题马上就来了。2.4 手动运行 sdkmanager看真实堆栈这个步骤是整套排查的灵魂。进入对应的目录直接执行Windows以 latest 为例cd /d %ANDROID_HOME%\cmdline-tools\latest\bin sdkmanager.bat --versionmacOS / Linuxcd $ANDROID_HOME/cmdline-tools/latest/bin ./sdkmanager --version如果一切正常会输出类似12.0这样的版本号。如果失败你会看到比 Flutter 提示详细得多的堆栈。我遇到最多的输出是这种Exception in thread main java.lang.UnsupportedClassVersionError: com/android/sdklib/tool/sdkmanager/SdkManagerCli has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0如果你看到的错误和我这个类似说明 Java 版本不对sdkmanager要求 Java 17但你当前运行的 JVM 只有 Java 11 甚至 8。另一种常见情况是The operation couldn’t be completed. Unable to locate a Java Runtime.这说明系统连合适的 Java 都找不到需要先安装 JDK或者设置 JAVA_HOME。还有一类错误发生在运行sdkmanager --licenses而不是sdkmanager --version时可能是网络代理或 SSL 证书问题。后面我会单独讲。3. 修复实战按根因解决手动执行后报错原因基本就浮出水面了。下面按概率从高到低列出修复方案。3.1 根因A缺少或错位 cmdline-tools如果你的手动执行结果是“找不到文件”或者“No such file or directory”基本就是 cmdline-tools 组件缺失或目录结构不对。最省事的办法是用 Android Studio 安装打开 Android Studio进入Settings或 Preferences→ Languages Frameworks → Android SDK → SDK Tools在列表里找到Android SDK Command-line Tools (latest)勾选点击 Apply 安装完成后检查cmdline-tools/latest/bin/sdkmanager是否存在。如果你不想打开 Android Studio也可以去官方命令行工具下载页下载对应平台的 compressed zip解压后得到一个cmdline-tools文件夹。注意官方 zip 解压后目录结构是cmdline-tools/cmdline-tools/bin很多人直接塞进 SDK 根目录导致最终路径变成SDK/cmdline-tools/bin/sdkmanager这也不对。正确做法是进入cmdline-tools文件夹把里面的内容放到一个名为latest的子目录中。也就是SDK/cmdline-tools/latest/bin/sdkmanager.bat如果之前已经有cmdline-tools/11.0这类版本目录也可以直接把它改名为latest效果一样。我自己的习惯是保留版本号目录再做一个latest目录指向当前正在使用的版本方便以后升级时对比。3.2 根因BJava 版本太旧无法驱动现代 sdkmanager新版 Android sdkmanager大致从 8.0 开始要求 Java 17这一点被坑的人最多。为什么因为不少人电脑上装着 JDK 8 或 JDK 11而且它们也能正常编译运行一般的 Flutter Android 工程于是压根没想到问题出在 Java 版本上。严格来说sdkmanager 报的是 class file version 61.0Java 17与 class file version 55.0Java 11不匹配。你要做的不是换一个老版本 sdkmanager而是给 sdkmanager 一个 Java 17 的运行环境。三种做法做法一设置 JAVA_HOME 指向 Android Studio 自带的 JBRAndroid Studio 从某个版本开始自带 JetBrains Runtime本质是定制版 OpenJDK版本通常就是 17 或 21而且路径固定Windows 默认路径C:\Program Files\Android\Android Studio\jbrmacOS 默认路径/Applications/Android Studio.app/Contents/jbr/Contents/Home在系统环境变量里把JAVA_HOME指到对应路径即可。Windows 可以这么设置setx JAVA_HOME C:\Program Files\Android\Android Studio\jbr注意如果路径里有空格不要自己加引号setx的语法里后面的值整体算一个参数不加额外引号。设置完记得重开终端让环境变量生效。macOS 临时生效的话export JAVA_HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home如果想永久生效就写到~/.zshrc或~/.bash_profile。之后重新跑一遍手动验证命令应该就能看到版本号了。做法二安装独立 JDK 17如果你不想依赖 Android Studio也可以直接装一个通用的 OpenJDK 17比如 Temurin 17 或 Oracle JDK 17。安装时勾选“设置 JAVA_HOME”省得自己再配。装完之后同样先验证java -version看到openjdk version 17.0.x再继续。做法三接受同时存在多个 JDK 的事实但要把优先级管好很多开发者的机器上不可能只有一套 JDK我也不建议为了一个 sdkmanager 卸载其他版本。更好的做法是把 Java 17 设为系统默认的 JAVA_HOME同时用工具链给不同项目指定不同 JDK。比如 Android Studio 的 Gradle JDK 设置、FVM 的环境变量等。这样 sdkmanager 能跑Gradle 构建也能按项目需要切换。作为长期方案我建议JAVA_HOME 永远指向一个 17 或 21 的 JDK。Flutter 新版和 Android Gradle Plugin 对 Java 17 的兼容性已经很稳定了不用再守着 JDK 8 不放。3.3 根因C目录权限、路径含空格或代理下载失败如果你的 sdkmanager 能手动运行--version但运行--licenses时依然崩溃问题往往不在 Java而在更隐蔽的系统层。比较典型的几类目录权限不足Windows 上如果 Android SDK 装在C:\Program Files (x86)\Android\android-sdk普通用户终端没有写权限sdkmanager 想往 SDK 目录写临时文件时会失败。解法是右键 SDK 根目录 → 属性 → 安全 → 编辑权限给当前用户发“完全控制”权限或者干脆把 SDK 挪到C:\Android\sdk这类不涉及系统保护的目录。macOS/Linux 上同理如果在/usr/local或/opt下当前用户可能没写权限用sudo chown -R $(whoami) /path/to/sdk把所有权交给当前用户更省心。路径中有空格或中文Android SDK 目录最好不要有空格也尽量不要有中文。如果你装在C:\Users\张三\AppData\Local\Android\Sdk某些工具解析路径时可能出问题。虽然现代版本大多已经能处理空格但“能处理”和“处理得好”是两回事。既然我们用命令行工具就把坑留少一点。代理问题sdkmanager --licenses需要从 Google 的仓库拉取许可信息。如果你的网络环境需要使用代理而 sdkmanager 没有配置代理就可能报出让人摸不着头脑的 SSL 异常。遇到这种情况先检查.android目录下有没有sdkmanager 的代理配置或者在 SDK 根目录下的cmdline-tools/latest/bin/sdkmanager脚本里看到代理相关参数。其实更直接的判断方式是手动执行sdkmanager --list如果列表能正常拉下来说明网络这块没问题如果连列表都拉不下来那就先解决网络和代理再回来处理 licenses。历史残留目录脏了如果上述都正常但问题还在可以清理一下本地授权缓存。Android licenses 存在用户主目录下的.android/licenses文件夹里里面是 Android SDK License、Android Auto Distribution License 等几个没有扩展名的文件。你可以把.android目录临时改名备份再重新运行flutter doctor --android-licenses。注意这只是恢复初始化不是把问题掩盖了如果还有残余错误备份恢复很关键。4. 不想敲命令用 Android Studio 图形界面兜底如果手动执行 sdkmanager 这一步对你来说太劝退或者整了半天 Java 还是没对齐还有一个办法能绕开命令行直接让 Android Studio 的图形界面来处理许可。4.1 SDK Manager 图形界面如何接过许可证任务打开 Android Studio按下面路径操作顶部菜单File → SettingsmacOS 是Android Studio → Preferences找到Languages Frameworks → Android SDK左侧能直接看到 SDK 路径和已安装的组件清单。要触发许可证窗口最直接的办法是切到SDK Platforms选项卡勾选一个尚未安装的 API Level点击 Apply。这时候 Android Studio 会弹出一个许可协议确认列表列出所有需要接受的协议并让你逐条勾选 Accept。把每个协议都勾上 Accept点 FinishAndroid Studio 会把这些许可写进.android/licenses目录。之后再回到终端执行flutter doctor如果 Flutter 能读出这些授权Android license status unknown就会消失整个流程就结束了。4.2 我说说为什么“图形界面法”也有局限性这个方法从体验上确实是“躺平式修复”但它有两个前提你的 Android Studio 版本和 SDK 版本不能太老。太老的版本里许可列表可能不包含新组件需要的协议导致部分新协议仍未被接受Flutter 要能正确读到 Android Studio 写入的授权文件。如果 Flutter 因为 PATH 或环境变量问题用了另一套 SDK授权文件写到 A 套 SDKFlutter 检查 B 套 SDK自然也会失败。所以图形界面法更适合“已经能用 Android Studio 正常开发只是 Flutter 这边报授权未知”的场景。如果连 Android Studio 的 SDK Manager 都打不开或者你根本没装 Android Studio那就还是得回到命令行方案。另外还有一个小技巧即使你用图形界面接受了许可也可以顺手在 Android Studio 的Terminal面板里敲一次%ANDROID_HOME%\cmdline-tools\latest\bin\sdkmanager.bat --licensesAndroid Studio 自带的终端会继承它的环境变量比你在系统终端敲命令少了环境变量干扰往往能直接跑通。这也是排查环境问题的一个低成本的“试金石”。5. 从源头不再踩坑一套稳定的环境配置流程解决完这一次我更想聊聊怎么让这种问题在以后少出现。毕竟 Flutter 开发不是只配一次环境就结束换电脑、升级 Flutter、升级 Android Studio每一步都可能让这类老问题卷土重来。5.1 我的环境配置清单我现在给新机器配置 Flutter Android 环境固定按这套顺序来几乎不会在 licenses 上踩坑先装 Java 17 JDK配置好 JAVA_HOME并把%JAVA_HOME%\bin加入 PATH安装 Android Studio并在 SDK Manager 里至少安装Android SDK Platform-ToolsAndroid SDK Build-ToolsAndroid SDK Command-line Tools (latest)一个当前常用的 Android Platform比如 Android 34设置 ANDROID_HOME 指向 SDK 根目录并把%ANDROID_HOME%\platform-tools加入 PATH打开新终端先执行sdkmanager --version确认 Java 与 sdkmanager 能协同工作再执行flutter doctor按提示处理剩余问题。这个方法的核心逻辑是在跑 Flutter 之前先保证 Android SDK 自身的工具链是完好的。好比你在用打包工具之前得先确认原料供应商能正常发货。5.2 一条命令验证环境是否完整我习惯在配环境时写一个小的检查脚本Windows 上存成一个.batmacOS/Linux 上存成一个.sh内容大致是Windows CMDecho off echo ANDROID_HOME%ANDROID_HOME% echo JAVA_HOME%JAVA_HOME% if defined JAVA_HOME ( %JAVA_HOME%\bin\java -version ) if exist %ANDROID_HOME%\cmdline-tools\latest\bin\sdkmanager.bat ( echo sdkmanager is OK ) else ( echo sdkmanager NOT FOUND )macOS / Linuxecho ANDROID_HOME$ANDROID_HOME echo JAVA_HOME$JAVA_HOME $JAVA_HOME/bin/java -version if [ -f $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager ]; then echo sdkmanager is OK else echo sdkmanager NOT FOUND fi运行一次所有关键路径一目了然。哪个变量没设、哪个文件缺失不需要再靠flutter doctor猜来猜去。5.3 个人经验碎碎念这次踩坑让我最深的体会是Flutter 的错误提示可以很简陋但不要借此偷懒。遇到Exception in thread main这种输出第一步不是去搜索整行报错而是先想清楚“这个命令在调用谁、它依赖什么”。一旦上手手动跑 sdkmanager问题范围立刻缩到 Java 版本、目录结构、权限这三块。另外还有一个细节值得留意很多人在网上看到的解决方案是“安装 Android SDK Tools旧版”也就是那个带 GUI 的SDK Manager.exe的旧工具。我建议别再用它了它是被官方弃用的历史组件和现代 Flutter 的兼容性时好时坏。用新版 Command-line Tools 才是正道。最后说一句如果你照着上面操作把sdkmanager --version跑通了那么flutter doctor --android-licenses大概率也已经正常了。如果还不行那就回到第 2 节手动执行sdkmanager --licenses看它具体卡在哪个环节——至少这一次它会给你一个真实、可读的错误信息而不是让你在Exception in thread main里干瞪眼。