Flutter 环境搭建 (Android)

目标

上一篇Flutter应用已经能在iOS，macOS和,chrome环境下正常运行了,这次把Android跑通。

环境

macOS 15.4.1

Visual Studio Code 1.99.3

Flutter 3.29.3 • channel stable • https://github.com/flutter/flutter.git
Framework • revision ea121f8859 (11 days ago) • 2025-04-11 19:10:07 +0000
Engine • revision cf56914b32
Tools • Dart 3.7.2 • DevTools 2.42.3

JDK 17
Gradle 8.10.2

环境搭建

Flutter的Android的工具链

• Android SDK Platform, API 35.0.2
• Android SDK Command-line Tools – 包括 ProGuard 等基本工具
• Android SDK Build-Tools – 包含构建 Android 应用的工具（可以下多个)
• Android SDK Platform-Tools – 包含 Android 平台所需的各种工具，包括 adb 工具。
• Android Emulator – 模拟器

最后效果

问题列表

网络:

网上试了一些方案,没有解决,下面这篇的方案在我的设备上是可以的

Android SDK更新设置代理详解：解决国内开发者下载难题

1. 自动代理配置 https://mirrors.aliyun.com
2. 验证代理是否生效
3. 下载Android SDK相关工具

主要是第二步让我看到了点曙光，网络测试时

1. www.baidu.com 能访问
2. www.google.com 超时 – 符合预期
3. dl.google.com 404 – 这个说明不是不能访问,只是地址不对,所以又下载验证了下，总算在跑了

设置下载SDK的路径

各个工具压缩包的大小

同意协议, 这里我因为不了解,所以Build-Tools多下了一个

从执行结果看,还是有因为超时失败的,比如https://dl.google.com/android/repository/build-tools_r36_macosx.zip
发现能ping通dl.google.com，而且能知道下载哪个包,可以直接用curl下载，一般不会有校验。

Preparing "Install Sources for Android 35 (revision 1)".
Downloading https://dl.google.com/android/repository/source-35_r01.zip
"Install Sources for Android 35 (revision 1)" ready.
Installing Sources for Android 35 in /Users/shepherd/Library/Android/sdk/sources/android-35
"Install Sources for Android 35 (revision 1)" complete.
"Install Sources for Android 35 (revision 1)" finished.
Preparing "Install Android SDK Build-Tools 35.0.1 v.35.0.1".
Downloading https://dl.google.com/android/repository/build-tools_r35.0.1_macosx.zip
"Install Android SDK Build-Tools 35.0.1 v.35.0.1" ready.
Installing Android SDK Build-Tools 35.0.1 in /Users/shepherd/Library/Android/sdk/build-tools/35.0.1
"Install Android SDK Build-Tools 35.0.1 v.35.0.1" complete.
"Install Android SDK Build-Tools 35.0.1 v.35.0.1" finished.
Preparing "Install Android SDK Platform 35 (revision 2)".
Downloading https://dl.google.com/android/repository/platform-35_r02.zip
"Install Android SDK Platform 35 (revision 2)" ready.
Installing Android SDK Platform 35 in /Users/shepherd/Library/Android/sdk/platforms/android-35
...
Preparing "Install Android Emulator v.35.4.9".
Downloading https://dl.google.com/android/repository/emulator-darwin_x64-13025442.zip
java.io.IOException: Connection closed at byte 88515719. Expected 393818294 bytes.
Warning: An error occurred while preparing SDK package Android Emulator: Connection closed at byte 88515719. Expected 393818294 bytes..
"Install Android Emulator v.35.4.9" failed.
Parsing /Users/shepherd/Library/Android/sdk/build-tools/35.0.1/package.xml
Parsing /Users/shepherd/Library/Android/sdk/platform-tools/package.xml
Parsing /Users/shepherd/Library/Android/sdk/platforms/android-35/package.xml
Parsing /Users/shepherd/Library/Android/sdk/sources/android-35/package.xml
java.net.SocketTimeoutException: Read timed out
Warning: An error occurred while preparing SDK package Android SDK Build-Tools 36: Read timed out.
java.io.IOException: Connection closed at byte 88515719. Expected 393818294 bytes.
Warning: An error occurred while preparing SDK package Android Emulator: Connection closed at byte 88515719. Expected 393818294 bytes..Preparing "Install Android SDK Build-Tools 36 v.36.0.0".
Downloading https://dl.google.com/android/repository/build-tools_r36_macosx.zip
java.net.SocketTimeoutException: Read timed out
Warning: An error occurred while preparing SDK package Android SDK Build-Tools 36: Read timed out.
"Install Android SDK Build-Tools 36 v.36.0.0" failed.
Preparing "Install Android Emulator v.35.4.9".
Downloading https://dl.google.com/android/repository/emulator-darwin_x64-13025442.zip
...

Flutter 执行 Android

Flutter驱动Android Studio工程成功运行到模拟器上

问题列表

flutter doctor

$ flutter doctor

两个问题,上一篇文章里是无法定位到Android SDK,现在能定位到了,看报错需要同意下协议

同意Android协议

# 会报错,依赖sdkmanager
$ flutter doctor --android-licenses
Android sdkmanager not found. Update to the latest Android SDK and ensure that the cmdline-tools are installed to resolve this.

在Android Studio界面选择了安装 command-line 工具后

下载完成后会在sdk > cmdline-tools目录下

# ~/.zshrc 追加环境变量
export PATH="sdk/command-tools/latest/bin/:$PATH"
source ~/.zshrc

再次执行sdkmanager无法打开

$ sudo xattr -d com.apple.quarantine ~/Library/Android/sdk/cmdline-tools/bin/sdkmanager

再次执行JDK版本过低…

JDK版本过低不支持sdkmanager

选择合适的平台和架构然后下载JDK 17

openjdk

然后复制到/Library/Java/JavaVirtualMachines/ 目录下

修改~/.zshrc 里的PATH,将java命令指向这个目录下的JDK 17

$ export JAVA_HOME=/Library/Java/JavaVirtualMachines/openlogic-openjdk-17.jdk/Contents/Home$ export PATH="$JAVA_HOME/bin:$PATH"

打印当前的JDK版本

$ java --version
openjdk 17.0.14 2025-01-21
OpenJDK Runtime Environment OpenLogic-OpenJDK (build 17.0.14+7-adhoc.admin.jdk17u)
OpenJDK 64-Bit Server VM OpenLogic-OpenJDK (build 17.0.14+7-adhoc.admin.jdk17u, mixed mode, sharing)

处理完成后,再次执行

# 成功完成协议的签署
$ flutter doctor --android-licenses

Maven地址的替换

1. maven.google.com google的maven库资源站 – 不能访问
2. pub.dev dart和flutter的官方开放库资源站 – 能访问
3. github.com – 慢,但勉强能访问

参考这个进行处理 【Flutter】flutter doctor network resources 报错，解决国内开发环境问题

但里面说要重新删除cache，因为昨天网问题,下载非常慢,我原来下过,大部分是不用删，不删改代码执行会报错,主要是因为有哈希校验，所以看了下,把几个大的(artifacts,dark-sdk,flutter_web_sdk)和相关的.stamp文件保留,然后执行会快很多

创建Android虚拟机

使用Android Studio界面创建虚拟机，下载镜像,还是网络问题,一直失败,还是通过浏览器下载放到

# 35是API;google_apis_playstore是界面的名字;x86_64是架构
.../sdk/system-images/android-35/google_apis_playstore/x86_64

但是界面识别不了，还是要求我下载。后面发现可以通过VSCode触发创建虚拟机(Create Android emulator),所以这个可以等后面再处理

Maven安装:卡在Flutter:Running Gradle task ‘assembleDebug’ - Exception in thread “main” java.util.zip.ZipException: zip END header not found

网上找的资料是gradle-wrapper.properties里的gradle的版本号

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip

本地gradle的安装目录,在~/.gradle目录,大小和gradle 差距很大,所以应该是gradle.zip没下载成功导致的。

解决方案:可以通过浏览器下载后放到对应目录

或者换源应该也可以,一开始没找到,所以用浏览器下载的方法。

# 换源改成腾讯的
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.10.2-all.zip

Maven下载依赖包相关

下载kotlin-compiler-embeddable超时

02e07463 Importing root project - 70% Download https://plugins.gradle.org/m2/org/jetbrains/kotlin/kotlin-compiler-embeddable/1.9.24/kotlin-compiler-embeddable-1.9.24.jar

从网上下载后放到这个路径下 ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-compiler-embeddable/1.9.24/3fbd9c879bd84704a4c457237ce625d02f8f3d3c/

Maven依赖冲突

照着网上的在settings.gradle.kts加了国内的源之后

* What went wrong:
Build was configured to prefer settings repositories over project repositories but repository 'maven' was added by build file 'build.gradle.kts'

* What went wrong:
Build was configured to prefer settings repositories over project repositories but repository 'Google' was added by build file 'build.gradle.kts'

解决方案: 去掉build.gradle.kts文件中的allprojects下的repositories内容

安装冲突

* What went wrong:
An exception occurred applying plugin request [id: 'dev.flutter.flutter-gradle-plugin']
> Failed to apply plugin 'dev.flutter.flutter-gradle-plugin'.> Build was configured to prefer settings repositories over project repositories but repository 'maven' was added by plugin 'dev.flutter.flutter-gradle-plugin'

这步卡了比较久,问了DeepSeek，是因为 setting.gradle.kts 里repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)指定包用setting显式设置的源才可以,id("dev.flutter.flutter-plugin-loader") version "1.0.0" 这一句加的源没在上面声明

解决方案:可以把配置改成

repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

最终的build.gradle.kts + setting.gradle.kts

// build.gradle.kts
allprojects {repositories {// maven { url = uri("https://maven.aliyun.com/repository/public") }// maven { url = uri("https://maven.aliyun.com/repository/google") }// google()// mavenCentral()// google()// mavenCentral()}
}val newBuildDir: Directory = rootProject.layout.buildDirectory.dir("../../build").get()
rootProject.layout.buildDirectory.value(newBuildDir)subprojects {val newSubprojectBuildDir: Directory = newBuildDir.dir(project.name)project.layout.buildDirectory.value(newSubprojectBuildDir)
}
subprojects {project.evaluationDependsOn(":app")
}tasks.register<Delete>("clean") {delete(rootProject.layout.buildDirectory)
}

// settings.gradle.kts
pluginManagement {val flutterSdkPath = run {val properties = java.util.Properties()file("local.properties").inputStream().use { properties.load(it) }val flutterSdkPath = properties.getProperty("flutter.sdk")require(flutterSdkPath != null) { "flutter.sdk not set in local.properties" }flutterSdkPath}includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")repositories {google()mavenCentral()gradlePluginPortal()}
}dependencyResolutionManagement {// repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)repositories {// 添加国内镜像源maven { url = uri("https://maven.aliyun.com/repository/public") }maven { url = uri("https://maven.aliyun.com/repository/google") }maven { url = uri("https://repo.huaweicloud.com/repository/maven") } // 华为云maven { url = uri("https://mirrors.tencent.com/nexus/repository/maven-public") } // 腾讯云// 后面报错会用到maven { url = uri("https://storage.flutter-io.cn/download.flutter.io")}maven { url = uri("https://maven.aliyun.com/repository/jcenter")}// 保留默认仓库（镜像源缺失时回退）google()mavenCentral()}
}plugins {id("dev.flutter.flutter-plugin-loader") version "1.0.0"id("com.android.application") version "8.7.0" apply falseid("org.jetbrains.kotlin.android") version "1.8.22" apply false
}include(":app")

小插曲: 关闭gradle自动更新

每次打开gradle都自动更新,现在有问题,自动更新影响思考,先关闭，打开首选项 > 设置，搜索Gradle，观后取消勾选。

NDK 安装

在VSCode的终端执行

$ cd android
$ ./gradlew clean build --refresh-dependencies

又是等待…

下载解压后放到sdk的对应目录下,重新执行gradle更新的命令

困惑:NDK的默认版本

错误提示下载 26.3.11579264，但是NDK 下载 已经标记过期了。

下面的flutter.ndkVersion值定义在flutter sdk的安装目录下的 .../flutter/packages/flutter_tools/gradle/src/main/groovy/flutter.groovy

android {namespace = "com.example.helloworld"compileSdk = flutter.compileSdkVersionndkVersion = flutter.ndkVersion...
}

没明白为什么会去下34的build-Tools,本地已经安装的是35和36,命令会下失败,手动下载34后放到sdk对应目录下

Checking the license for package Android SDK Build-Tools 34 in ~/Library/Android/sdk/licenses
License for package Android SDK Build-Tools 34 accepted.
Preparing "Install Android SDK Build-Tools 34 v.34.0.0".
...

找不到flutter_embedding_debug包

The org.gradle.api.plugins.Convention type has been deprecated. This is scheduled to be removed in Gradle 9.0. Consult the upgrading guide for further information: https://docs.gradle.org/8.10.2/userguide/upgrading_version_8.html#deprecated_access_to_conventionsat Build_gradle$3.execute(build.gradle.kts:29)

用的gradle是8.10.2,有警告,但是不阻塞

> Could not resolve all dependencies for configuration ':app:debugRuntimeClasspath'.> Could not find io.flutter:flutter_embedding_debug:1.0.0-cf56914b326edb0ccb123ffdc60f00060bd513fa.> Could not resolve all dependencies for configuration ':app:debugRuntimeClasspath'.> Could not find io.flutter:arm64_v8a_debug:1.0.0-cf56914b326edb0ccb123ffdc60f00060bd513fa.

上面两个包找不到导致无法继续执行

> Task :app:checkDebugAarMetadata FAILEDFAILURE: Build failed with an exception.

根据参考4,在settings.gradle.kts添加

maven { url = uri("https://storage.flutter-io.cn/download.flutter.io")}
maven { url = uri("https://maven.aliyun.com/repository/jcenter")}

网络差可能下载失败还会报错,只能重新执行

下指定版本的cmake

旧版本cmake下载

本来要编译一个,但是下载下来了,这步跳过

成功

体验与收获

1. 本地搭了Android开发环境,了解了Android的几个目录的工具用途
2. Flutter运行Android平台
3. 很多问题都是网络的原因,大部分时间在下载资源
4. 不兼容的问题蛮折腾,开发容易,维护难
5. 多去使用AI

参考

1. 开始在 macOS 上构建 Flutter Android 应用
2. Android SDK更新设置代理详解：解决国内开发者下载难题
3. 【Flutter】flutter doctor network resources 报错，解决国内开发环境问题
4. 使用Android Studio开发flutter项目报错：Execution failed for task ':app:checkDebugAarMetad