Debian 上 Flutter 编译失败的定位与修复指南
一、快速自检与环境修复
- 更新系统并补齐基础依赖（构建、压缩、SSL、图像、字体、GTK 等）：
- sudo apt update && sudo apt full-upgrade -y
- sudo apt install -y build-essential libssl-dev libffi-dev zlib1g-dev libjpeg-dev libpng-dev libfreetype6-dev libgtk-3-dev
- 校验 Flutter 环境并逐项修复：
- flutter doctor -v
- 若提示 Java/Android 相关错误，先安装 JDK 11，再执行 flutter doctor --android-licenses 接受协议
- 若提示缺失系统库（如 libgconf-2-dev 等），按提示安装后重跑 flutter doctor
- 更新 SDK 与依赖缓存：
- flutter upgrade
- 清理构建缓存：flutter clean；必要时删除 ~/.gradle/caches/ 后再试
- 检查磁盘与内存（构建需要充足空间与内存，建议预留 10GB+ 可用空间）
二、Android 构建常见报错与修复
- Gradle 与 Java 版本不匹配
- 现象：Gradle 启动失败、Kotlin 编译异常、AGP 要求 Java 11
- 处理：
- 明确使用 JDK 11，可通过 flutter config --jdk-dir <jdk11_path> 指定
- 在 android/gradle/wrapper/gradle-wrapper.properties 调整 Gradle 版本，使其与 AGP/Java 兼容
- 同步升级 AGP 与 Kotlin 插件版本，避免缓存冲突
- minSdkVersion 过低
- 现象：Manifest merger 失败，提示库要求 minSdkVersion >= 19
- 处理：在项目 android/app/build.gradle 的 defaultConfig 中将 minSdkVersion 提升到至少 19（或更高以适配依赖库）
- 无法找到 Android SDK 或许可未接受
- 现象：doctor 报 Android toolchain 异常
- 处理：
- 配置 ANDROID_SDK_ROOT/ANDROID_HOME，安装命令行工具与平台包
- 执行 flutter doctor --android-licenses 并全部接受
三、Linux 桌面端构建常见报错与修复
- 架构不匹配（多发生于 arm64 设备）
- 现象：链接时报错，例如 pdfium 为 x86_64 而目标为 aarch64
- 处理：
- 避免混用架构的二进制（如 snap 与 x86_64 SDK 混用）
- 使用与设备架构一致的 Flutter SDK 与依赖，或改用官方 arm64 包/构建
- 系统依赖缺失
- 现象：构建/运行阶段报缺 libgconf-2-dev 等
- 处理：sudo apt install -y libgconf-2-dev 等缺失库后重试
- 桌面运行库不完整
- 现象：运行或调试时报 GTK/OpenGL/字体相关错误
- 处理：确保安装 libgtk-3-dev 等桌面运行依赖，并使用稳定渠道的 Flutter 版本
四、仍未解决时的高效求助方式
- 提供可复现的最小项目与完整日志
- 命令：flutter build linux --debug -v 或 flutter run -v
- 附加：flutter doctor -v、java -version、lsb_release -a、uname -m、df -h
- 常见网络与权限问题
- 配置国内镜像源加速依赖下载（如 pub、Gradle）
- 检查项目/缓存目录权限，避免使用 root 直接构建
- 环境隔离
- 使用 Docker 构建，减少宿主机环境影响（示例 Dockerfile 基于 Ubuntu 20.04，按需调整）
