Flutter 构建环境踩坑记录

环境信息项目值操作系统Linux x86_64Flutter 版本3.44.9 stable2026-08-05 发布JDK21.0.11Android SDK编译目标 36构建工具 36.0.0Gradle9.3.1数据目录/mnt/shared/mybilibili/mybilibili-app-flutter问题清单1. Flutter 引擎 Maven 包找不到现象构建报错Could not find io.flutter:arm64_v8a_debug:1.0.0-5a2a6a42...搜索 Google Maven、Maven Central、华为云镜像均返回 404。原因Flutter 3.44.9 引擎版本太新仅发布 2 周国内镜像未同步完成。搜索路径与结果镜像源结果Google Maven不包含 flutter 引擎Maven Central不包含华为云镜像404未同步新版腾讯云镜像200版本存在解决切换到腾讯云镜像该版本已同步响应时间 0.1-1s。bashexport FLUTTER_STORAGE_BASE_URLhttps://mirrors.cloud.tencent.com/flutter2. Dart Pub 包下载失败现象flutter pub get报version solving failed或authorization failed。原因PUB_HOSTED_URL原指向清华镜像新版flutter_lints等包不存在或需要认证。解决改用 pub.dev 官方源。bashexport PUB_HOSTED_URLhttps://pub.dev3. media_kit mpv jar 下载超时现象Gradle 构建时下载 GitHub Release 上的 4 个 jar 文件连接超时。原因网络限制导致下载缓慢30 秒仅能下载 3MB总需 5.7MB。解决手动下载全部 4 个 jar校验 MD5 后放入构建缓存目录bash# 缓存目录.../build/media_kit_libs_android_video/v1.1.7/ # 4 个文件及 MD5 # default-arm64-v8a.jar 83df25b61193af8fa815e373143ac9af # default-armeabi-v7a.jar 22e21526fefc0a2b8f17adbec9f57590 # default-x86_64.jar 6fa26bf0459b11f1c0b0dbc29e5b940d # default-x86.jar 0d742b756dc9d1fcd84ea271d8b68f324. Kotlin/JVM 目标版本冲突现象Inconsistent JVM Target Compatibility Between Java and Kotlin Tasksgradle 报compileDebugJavaWithJavac (11)与compileDebugKotlin (1.8)不匹配。原因volume_controller和screen_brightness_android两个插件使用 Kotlin 1.7.21、设置jvmTarget 1.8JDK 21 默认 Java 目标为 11Kotlin 2.x 编译器要求两者一致。解决直接修改 pub-cache 中插件的 build.gradle 文件diff# volume_controller-2.0.8/android/build.gradle - compileSdkVersion 31 compileSdkVersion 36 - kotlinOptions { jvmTarget 1.8 } kotlinOptions { jvmTarget 17 } compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } # screen_brightness_android-0.1.02/android/build.gradle - compileSdkVersion 31 compileSdkVersion 36 - compileOptions { sourceCompatibility VERSION_1_8; targetCompatibility VERSION_1_8 } compileOptions { sourceCompatibility VERSION_17; targetCompatibility VERSION_17 } - kotlinOptions { jvmTarget 1.8 } kotlinOptions { jvmTarget 17 }5. 插件 compileSdk 版本过旧现象22 issues were found when checking AAR metadata插件编译目标为 31依赖要求 36。涉及的插件插件旧值新值media_kit_video3136volume_controller3136screen_brightness_android3136解决将每个插件的compileSdkVersion 31改为compileSdkVersion 36。6. Release 版缺少 INTERNET 权限现象App 启动后报SocketException: Operation not permitted, errno 1连接后端失败。原因Flutter 仅在 debug 版自动添加INTERNET权限release 版需在AndroidManifest.xml中显式声明。解决在主 manifest 中添加xmlmanifest xmlns:androidhttp://schemas.android.com/apk/res/android uses-permission android:nameandroid.permission.INTERNET/ application ...7. API 地址指向 localhost容器内不通现象App 连接localhost:8080容器内指向自身而非宿主机。原因App 硬编码了http://localhost:8080/api/v1在容器内 localhost 指向 Android 容器本身。解决改为宿主机内网 IP文件行旧值新值lib/core/api/client.dart:7baseUrlhttp://localhost:8080http://192.168.31.204:8080lib/core/api/live_api.dart:42streamUrlhttp://localhost:8080http://192.168.31.204:80808. Waydroid 平板样式现象Waydroid 显示为平板布局1024x568密度 180。原因默认分辨率为 1024x568密度 180dpi最小宽度 505dpAndroid 呈现平板 UI。解决临时覆盖重启后失效bashadb shell wm size 1080x1920 adb shell wm density 420持久化编辑/var/lib/waydroid/waydroid.cfg在[properties]段添加ini[properties] ro.sf.lcd_density 420最终环境配置永久环境变量~/.bashrcbashexport FLUTTER_STORAGE_BASE_URLhttps://mirrors.cloud.tencent.com/flutter export PUB_HOSTED_URLhttps://pub.dev编译命令bash# Debug 全架构192MB不适合发布 flutter build apk --debug # Release 按架构拆分推荐 flutter build apk --release --split-per-abi产物位置bash# Debug build/app/outputs/flutter-apk/app-debug.apk # 192MB # Release按架构拆分 build/app/outputs/flutter-apk/app-arm64-v8a-release.apk # 32MB build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk # 29MB build/app/outputs/flutter-apk/app-x86_64-release.apk # 37MB后续维护注意事项flutter pub upgrade后pub-cache 重建需重新打volume_controller、screen_brightness_android、media_kit_video三个插件的补丁Flutter SDK 升级后先确认腾讯云镜像是否已有新版本——curl -I https://mirrors.cloud.tencent.com/flutter/download.flutter.io/io/flutter/arm64_v8a_debug/1.0.0-新哈希/...pom宿主机 IP 变化需同步更新client.dart和live_api.dart中的 IP 地址flutter clean后media_kit 的 mpv jar 缓存被清需重新预下载或首次构建时多等待 3 分钟Waydroid 重启后若未持久化分辨率/密度需重新执行adb shell wm size 1080x1920 wm density 420