Back to Details

flutter-android-build-triage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Android build triage

Flutter Android构建问题排查

Fix a failing Flutter Android build by locating the blame line — the one line in Gradle's wall of output that names the actual culprit (a plugin, a version, a missing symbol, a full disk) — and matching it to the fix table below. Everything above the blame line is noise.
通过定位问题根源行来修复失败的Flutter Android构建——Gradle大量输出中指明实际问题（插件、版本、缺失符号、磁盘已满）的那一行——并匹配下方的修复表。根源行之上的所有内容都是无效信息。

Steps

步骤

  1. Reproduce and capture. Run the failing build and keep the output: 
    flutter build apk --debug 2>&1 | grep -B5 -A15 -iE 'what went wrong|error:|caused by|Could not|ENOSPC|No space|license|sdk' | head -60
    Completion criterion: you have 10–60 lines containing the blame line — the line that names the missing/incompatible thing.
  2. Match the blame line to a row in the symptom table and apply that fix. If the line names a native function (e.g. 
    sqlite3_initialize
    ), it's a packaging problem, not Dart code — see the native-libs row.
  3. Verify with a clean build: 
    flutter clean && flutter pub get && flutter build apk --debug
    . Completion criterion: output ends with 
    Built build/app/outputs/flutter-apk/app-debug.apk
    .
  4. If Dart APIs changed (e.g. after a package downgrade), fix call sites and re-run 
    flutter analyze
    + 
    flutter test
    until both are clean.
  1. 复现并捕获输出。运行失败的构建并保存输出： 
    flutter build apk --debug 2>&1 | grep -B5 -A15 -iE 'what went wrong|error:|caused by|Could not|ENOSPC|No space|license|sdk' | head -60
    完成标准：你已获取包含问题根源行的10–60行内容——该行指明了缺失/不兼容的对象。
  2. 将问题根源行与症状表中的行匹配并应用相应修复。如果该行提到原生函数（如
    sqlite3_initialize
    ），则属于打包问题，而非Dart代码问题——请查看原生库相关行。
  3. 通过清理构建验证：
    flutter clean && flutter pub get && flutter build apk --debug
    。 完成标准：输出以
    Built build/app/outputs/flutter-apk/app-debug.apk
    结尾。
  4. 如果Dart API发生变更（例如包降级后），修复调用站点并重新运行
    flutter analyze
    + 
    flutter test
    ，直到两者都无问题。

Symptom table

症状表

Blame lineDiagnosisFix
NullPointerException
in Gradle / 
Could not apply plugin
/ AGP 9-era errors		Flutter template shipped AGP 9.0.1 + Gradle 9.1; some pub plugins (older DSL) are incompatible with AGP 9Pin AGP 8.9.1 in 
android/settings.gradle.kts
and Gradle 8.14.3 in 
android/gradle/wrapper/gradle-wrapper.properties
; re-run the build
Plugin error mentioning 
namespace
or DSL from 2021 (e.g. 
file_picker 3.0.4
)		Plugin version pinned far too old (no 
namespace
, no modern DSL)		Upgrade the plugin to a current major (
flutter pub add file_picker:^10.0.0
); watch for transitive conflicts and adjust neighbors (e.g. 
flutter_secure_storage:^10
)
Runtime 
Couldn't resolve native function 'sqlite3_initialize'
/ 
No available native assets
sqlite3
3.x needs native-assets build hooks; 
sqlite3_flutter_libs 0.6.0+eol
is an empty stub that bundles no lib		Downgrade to 
sqlite3:^2.9.0
+ 
sqlite3_flutter_libs:^0.5.28
(classic bundling, FTS5 works); note 
close()
→ 
dispose()
in 2.x
ENOSPC: no space left on device
/ Gradle 
Could not download
(403/404) / pub cache missing packages		Disk full (often >95%); partially-written caches corrupt 
.pub-cache
Free space (
df -h
, prune 
~/.gradle/wrapper/dists
, 
build/
), then 
flutter pub get
to re-download missing packages; rerun build
.pub-cache
missing packages after an interrupted run		Corrupted cache from an earlier ENOSPC/crashRun 
flutter pub get
(it re-fetches); verify with 
flutter analyze
问题根源行诊断结果修复方案
Gradle中出现
NullPointerException
/ 
Could not apply plugin
/ AGP 9相关错误		Flutter模板默认使用AGP 9.0.1 + Gradle 9.1；部分pub插件（旧版DSL）与AGP 9不兼容在
android/settings.gradle.kts
中固定AGP版本为8.9.1，在
android/gradle/wrapper/gradle-wrapper.properties
中固定Gradle版本为8.14.3；重新运行构建
插件错误提及
namespace
或2021年的DSL（如
file_picker 3.0.4
）		插件版本过于陈旧（无
namespace
，无现代DSL）		将插件升级至最新主版本（
flutter pub add file_picker:^10.0.0
）；注意传递性冲突并调整相关依赖（如
flutter_secure_storage:^10
）
运行时出现
Couldn't resolve native function 'sqlite3_initialize'
/ 
No available native assets
sqlite3
3.x需要原生资源构建钩子；
sqlite3_flutter_libs 0.6.0+eol
是不包含任何库的空存根		降级至
sqlite3:^2.9.0
+ 
sqlite3_flutter_libs:^0.5.28
（经典打包方式，FTS5可正常工作）；注意2.x版本中
close()
需改为
dispose()
ENOSPC: no space left on device
/ Gradle提示
Could not download
（403/404） / pub缓存缺失包		磁盘已满（通常使用率>95%）；部分写入的缓存损坏了
.pub-cache
释放空间（
df -h
，清理
~/.gradle/wrapper/dists
、
build/
目录），然后执行
flutter pub get
重新下载缺失的包；重新运行构建
中断运行后
.pub-cache
缺失包		之前的ENOSPC/崩溃导致缓存损坏运行
flutter pub get
（会重新获取包）；通过
flutter analyze
验证

Reference

参考信息

  • Env stack that worked here: AGP 8.9.1 + Gradle 8.14.3, 
    flutter_secure_storage ^10
    , 
    file_picker ^10
    , 
    sqlite3 ^2.9
    + 
    sqlite3_flutter_libs ^0.5
    , minSdk 23.
  • A debug APK is ~150MB; installs over wifi adb are slow but fine (300s timeout).
  • Check disk pressure before blaming the network: 
    df -h /System/Volumes/Data
    — most "download failed" errors on a full disk are ENOSPC in disguise.
  • 验证有效的环境栈：AGP 8.9.1 + Gradle 8.14.3，
    flutter_secure_storage ^10
    ，
    file_picker ^10
    ，
    sqlite3 ^2.9
    + 
    sqlite3_flutter_libs ^0.5
    ，minSdk 23。
  • 调试APK约150MB；通过wifi adb安装速度较慢但可行（超时时间300秒）。
  • 在质疑网络问题前先检查磁盘压力：
    df -h /System/Volumes/Data
    —— 磁盘已满时大多数“下载失败”错误实际上是ENOSPC的伪装。