最近在玩Flutter，碰到一些问题在这里分享给大家，下次在 Linux（如 Ubuntu）环境下安装 Flutter 并配置 Android 开发环境时遇到的典型问题、原因及解决方案，适用于开发者快速排错。

---

1. ❌ 错误：The Flutter directory is not a clone of the GitHub project

原因

• 直接从 GitHub 下载 ZIP 包解压使用，而非通过 git clone。
• Flutter 工具链依赖 .git 目录进行版本管理和更新。

解决方案

# 删除错误安装的 Flutter
rm -rf flutter

# 使用 git 正确克隆（推荐 stable 分支）
git clone https://github.com/flutter/flutter.git -b stable

# 将 bin 目录加入 PATH（以 ~/.zshrc 为例）
echo 'export PATH="$PATH:$HOME/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

✅ 验证：flutter --version 应显示 Git 提交信息。

---

2. ❌ 错误：cmdline-tools component is missing

原因

• Android SDK 缺少命令行工具包（sdkmanager, avdmanager 等）。
• Flutter 依赖这些工具管理 SDK 组件和构建 APK。

解决方案（推荐图形化方式）

1. 打开 Android Studio
2. 进入 Tools → SDK Manager → SDK Tools
3. 勾选 ☑️ Android SDK Command-line Tools (latest)
4. 点击 Apply 安装

⚠️ 手动安装需确保目录结构为：
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager

---

3. ❌ 错误：Android sdkmanager not found

原因

• sdkmanager 未安装，或
• ANDROID_HOME 或 PATH 环境变量未正确设置。

解决步骤

(1) 确认 SDK 路径（默认为 ~/Android/Sdk）

ls ~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager

(2) 设置环境变量（添加到 ~/.zshrc 或 ~/.bashrc）

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

source ~/.zshrc  # 生效配置

(3) 告诉 Flutter SDK 位置（非默认路径时）

flutter config --android-sdk /path/to/your/sdk

---

4. ❌ 错误：Please set the JAVA_HOME variable

原因

• Android 构建工具（Gradle、sdkmanager）需要 JDK。
• 系统未安装 JDK，或未设置 JAVA_HOME。

解决方案

(1) 安装 OpenJDK 17（官方推荐）

sudo apt update
sudo apt install openjdk-17-jdk -y

(2) 查找 JDK 路径

dirname $(dirname $(readlink -f $(which java)))
# 输出示例：/usr/lib/jvm/java-17-openjdk-amd64

(3) 设置 JAVA_HOME

# 添加到 ~/.zshrc
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

source ~/.zshrc

✅ 验证：echo $JAVA_HOME 和 $JAVA_HOME/bin/java -version

---

5. ❌ 错误：Android license status unknown

原因

• 未接受 Android SDK 许可协议。

解决方案

flutter doctor --android-licenses

按提示输入 y 接受所有协议。

⚠️ 若报 Java 版本错误，请确保使用 JDK 17（JDK 21+ 可能不兼容）。

---

6. ⚠️ 警告：Linux toolchain - develop for Linux desktop 报错

原因

• 缺少 Linux 桌面开发依赖（clang, ninja, GTK 等）。

是否需要处理？

• 仅开发 Android App？→ 可忽略！
• 需要构建 Linux 桌面应用？→ 安装依赖：

  sudo apt install clang cmake ninja-build pkg-config libgtk-3-dev
  

---

7. 🌐 网络问题：无法访问 developer.android.com

解决方案

• 优先使用 Android Studio 图形界面安装组件（自动处理下载）。
• 国内用户可尝试清华镜像加速 Flutter：

  export FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter
  export PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
  

---

✅ 最终验证命令

flutter doctor

期望输出：

[✓] Flutter (Channel stable, ...)
[✓] Android toolchain - develop for Android devices
[✓] Chrome - develop for the web
[!] Linux toolchain - ...  # 可忽略（除非做 Linux 桌面）
[✓] Connected device

---

🔁 附：一键检查清单

检查项	命令
Flutter 是否 Git 克隆	ls .git in flutter dir
cmdline-tools 是否存在	ls $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager
JAVA_HOME 是否设置	echo $JAVA_HOME
sdkmanager 是否可用	sdkmanager --version
许可证是否接受	flutter doctor 无 license 警告

---

💡 提示：整个过程的核心是 Android SDK + cmdline-tools + JDK 17 + 正确环境变量。只要这四者到位，Flutter Android 开发环境即可正常工作。

---

✅ 完成以上配置后，即可运行：

flutter create my_app
cd my_app
flutter run            # 连接手机调试
flutter build apk      # 生成 release APK