Flutter 环境搭建 (Android)

目标

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

环境

macOS 15.4.1

Visual Studio Code 1.99.3

Flutter 3.29.3 • channel stable • github.com/flutter/flu... 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更新设置代理详解：解决国内开发者下载难题

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

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

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

设置下载SDK的路径

各个工具压缩包的大小

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

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

bash 复制代码

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

sh 复制代码

$ flutter doctor

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

同意Android协议

sh 复制代码

# 会报错,依赖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目录下

sh 复制代码

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

再次执行sdkmanager无法打开

sh 复制代码

$ 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

sh 复制代码

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

$ export PATH="$JAVA_HOME/bin:$PATH"

打印当前的JDK版本

sh 复制代码

$ 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)

处理完成后,再次执行

sh 复制代码

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

Maven地址的替换

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

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

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

创建Android虚拟机

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

sh 复制代码

# 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的版本号

ruby 复制代码

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

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

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

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

ruby 复制代码

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

Maven下载依赖包相关

下载kotlin-compiler-embeddable超时

bash 复制代码

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加了国内的源之后

csharp 复制代码

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

csharp 复制代码

* 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内容

安装冲突

bash 复制代码

* 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" 这一句加的源没在上面声明

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

bash 复制代码

repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

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

java 复制代码

// 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)
}

java 复制代码

// 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 false
    id("org.jetbrains.kotlin.android") version "1.8.22" apply false
}

include(":app")

小插曲: 关闭gradle自动更新

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

NDK 安装

在VSCode的终端执行

sh 复制代码

$ 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

kotlin 复制代码

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

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

perl 复制代码

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包

bash 复制代码

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_conventions
        at Build_gradle$3.execute(build.gradle.kts:29)

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

sh 复制代码

> 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.

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

ruby 复制代码

> Task :app:checkDebugAarMetadata FAILED

FAILURE: Build failed with an exception.

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

java 复制代码

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

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

下指定版本的cmake

旧版本cmake下载

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

成功

体验与收获

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