Windows 10 Android 构建配置指南

本文档记录在 Windows 10 上构建 Android APK 的环境配置、依赖安装和常见问题解决。

环境信息

组件	版本
操作系统	Windows 10 专业版 22H2
Flutter	3.38.9 (Dart 3.10.8)
Java	1.8.0_301 + OpenJDK 21 (Android Studio 自带)
Android SDK	36.1.0
Gradle	8.13
Android Gradle Plugin	8.1.0
Kotlin	1.9.10

环境配置步骤

1. 安装 Flutter

powershell 复制代码

# 下载 Flutter SDK
# https://docs.flutter.dev/get-started/install/windows

# 添加到环境变量
# Path += H:\flutter\bin

2. 安装 Android Studio

下载：https://developer.android.com/studio
安装时选择 Android SDK、Android SDK Platform-Tools
安装 Android 13 (API 33) SDK

3. 配置 Android SDK 路径

powershell 复制代码

# 告诉 Flutter Android SDK 的位置
flutter config --android-sdk "H:\Android\Sdk"

4. 接受 Android 许可证

powershell 复制代码

flutter doctor --android-licenses
# 对每个许可证输入 y 接受

5. 验证环境

powershell 复制代码

flutter doctor

依赖配置

pubspec.yaml 关键依赖

yaml 复制代码

dependencies:
  flutter:
    sdk: flutter

  # State Management
  provider: ^6.1.1

  # Local Storage
  sqflite: ^2.4.0
  path_provider: ^2.1.4
  shared_preferences: ^2.3.0

  # Internationalization
  intl: ^0.20.2
  flutter_localizations:
    sdk: flutter

  # Utils
  uuid: ^4.3.1

Android 配置文件

gradle.properties

properties 复制代码

org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=1G -Dfile.encoding=UTF-8
android.useAndroidX=true
android.enableJetifier=true

注意： 默认内存配置 -Xmx768M -XX:MaxMetaspaceSize=256M 会导致内存不足错误。

gradle-wrapper.properties

properties 复制代码

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

build.gradle.kts (项目级)

kotlin 复制代码

buildscript {
    ext.kotlin_version = "1.9.10"
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.1.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
    }
}

app/build.gradle.kts

kotlin 复制代码

android {
    namespace = "com.bucketlist.bucketList"
    compileSdk = 34

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }

    defaultConfig {
        applicationId = "com.bucketlist.bucketList"
        minSdk = 21
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

构建命令

powershell 复制代码

# 安装依赖
flutter pub get

# 清理构建缓存（出现问题时使用）
flutter clean

# 构建 Release APK
flutter build apk --release

# APK 输出位置
# build\app\outputs\flutter-apk\app-release.apk

常见问题与解决方案

1. cmdline-tools 组件缺失

错误信息：

复制代码

cmdline-tools component is missing

解决方案：

在 Android Studio 中安装：

Tools → SDK Manager
SDK Tools 选项卡
勾选 Android SDK Command-line Tools (latest)
点击 Apply 安装

2. Android SDK Platform 缺失

错误信息：

复制代码

Could not determine the dependencies of task ':sqflite:compileReleaseJavaWithJavac'.
Failed to install the following SDK components: platforms;android-33

解决方案：

在 Android Studio 的 SDK Manager 中安装 Android 13.0 (API 33)

3. 依赖版本冲突

错误信息：

复制代码

Because every version of flutter_localizations from sdk depends on intl 0.20.2
and bucket_list depends on intl ^0.18.1, flutter_localizations from sdk is forbidden.

解决方案：

更新 pubspec.yaml 中的 intl 版本：

yaml 复制代码

intl: ^0.20.2

然后运行：

powershell 复制代码

flutter pub get

4. CardTheme 类型错误

错误信息：

复制代码

The argument type 'CardTheme' can't be assigned to the parameter type 'CardThemeData?'.

解决方案：

修改 lib/utils/app_theme.dart：

dart 复制代码

// 错误
cardTheme: CardTheme(...)

// 正确
cardTheme: CardThemeData(...)

5. path_provider_android 编译错误

错误信息：

复制代码

error: cannot find symbol
PluginRegistry.Registrar registrar

解决方案：

powershell 复制代码

# 升级依赖到最新版本
flutter pub upgrade --major-versions

6. ic_launcher_foreground 资源缺失

错误信息：

复制代码

resource mipmap/ic_launcher_foreground not found

解决方案：

删除 adaptive-icon 配置：

powershell 复制代码

rm -rf android/app/src/main/res/mipmap-anydpi-v26

7. Kotlin 增量编译缓存损坏

错误信息：

复制代码

Could not close incremental caches
this and base files have different roots

解决方案：

powershell 复制代码

flutter clean
flutter build apk --release

8. 内存不足 (OutOfMemoryError)

错误信息：

复制代码

java.lang.OutOfMemoryError: Metaspace

解决方案：

修改 android/gradle.properties：

properties 复制代码

# 从
org.gradle.jvmargs=-Xmx768M -XX:MaxMetaspaceSize=256M

# 改为
org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=1G

9. Gradle 版本过低

错误信息：

复制代码

Minimum supported Gradle version is 8.13. Current version is 8.3

解决方案：

修改 android/gradle/wrapper/gradle-wrapper.properties：

properties 复制代码

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

Flutter Doctor 正常输出

复制代码

[√] Flutter (Channel stable, 3.38.9)
[√] Windows Version (10 专业版 64 位, 22H2, 2009)
[√] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
[√] Chrome - develop for the web
[√] Connected device
[√] Network resources

输出信息

APK 路径： build\app\outputs\flutter-apk\app-release.apk

示例输出：

复制代码

√ Built build\app\outputs\flutter-apk\app-release.apk (49.4MB)

Windows 10 Android 构建配置指南