---

## ⭐ 概览

目标：在 Debian 12 上搭建可以 **本地编译 Android 原生 APK** 的环境，包含：

- ✅ OpenJDK (推荐 17)
    
- ✅ Android SDK 命令行工具（cmdline-tools）
    
- ✅ Platform tools（adb）与 build-tools、platforms
    
- ✅ 可选：NDK / CMake（用于原生 C/C++）
    
- ✅ Gradle（用于构建）
    

适用场景：CI、无 GUI 的服务器、或仅需命令行编译的开发环境。

---

## 🧾 前置条件

- 一台运行 **Debian 12** 的机器（有 sudo 权限）
    
- 稳定的网络（用于下载 SDK 与工具）
    
- 建议至少 10GB 可用磁盘空间（SDK + 系统镜像可能占用）
    

---

## 1️⃣ 安装基础工具

先更新并安装基础依赖：

```bash
sudo apt update
sudo apt install -y git unzip wget curl zip build-essential
```

这些工具用于下载、解压、构建等。

---

## 2️⃣ 安装 JDK（推荐：OpenJDK 17）

Android Gradle Plugin（AGP）对 JDK 有版本要求，JDK 17 是安全选择：

```bash
sudo apt install -y openjdk-17-jdk
```

检查版本：

```bash
java -version
# 期望输出类似：openjdk version "17.x"
```

---

## 3️⃣ 下载并安装 Android SDK 命令行工具

去 Google 官方下载 `commandlinetools` 压缩包，或者用 wget（示例）：

```bash
mkdir -p $HOME/Android/cmdline-tools
cd $HOME/Android/cmdline-tools
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O cmdline-tools.zip
unzip cmdline-tools.zip
# 有时解压出来的目录名是 cmdline-tools，移动或重命名为 latest：
mv cmdline-tools latest
```

> 🔔 注意：实际下载链接和版本会随时间变化，请按需到 Android 官方网站获取最新版。

---

## 4️⃣ 配置环境变量（推荐写入 `~/.bashrc` 或 `~/.zshrc`）

将 SDK 路径加入环境变量，保证 `sdkmanager`、`adb` 等工具可用：

```bash
# 在 ~/.bashrc 或 ~/.zshrc 添加：
export ANDROID_HOME=$HOME/Android
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH

# 使之生效：
source ~/.bashrc
```

---

## 5️⃣ 使用 sdkmanager 安装常用组件

通过 `sdkmanager` 安装 `platform-tools`、指定 Android 平台与 build-tools：

```bash
sdkmanager --sdk_root=$ANDROID_HOME "platform-tools" "platforms;android-34" "build-tools;34.0.0"
```

可选安装（若需要 NDK / CMake 编译原生代码）：

```bash
sdkmanager "ndk;26.1.10909125" "cmake;3.22.1"
```

如果是自动接受许可，可以使用：

```bash
yes | sdkmanager --licenses
```

---

## 6️⃣ 安装 Gradle（可选：系统级）

Android 项目通常随 Gradle Wrapper（`gradlew`）一起提供，能自动下载合适版本。但若想系统安装：

```bash
wget https://services.gradle.org/distributions/gradle-8.7-bin.zip -P /tmp
sudo unzip -d /opt/gradle /tmp/gradle-8.7-bin.zip
# 添加到 PATH（写入 ~/.bashrc）：
export PATH=/opt/gradle/gradle-8.7/bin:$PATH
```

检查：

```bash
gradle -v
```

---

## 7️⃣ 创建或获取一个示例 Android 项目并编译

如果你已经有一个项目，进入项目目录并使用 Gradle Wrapper：

```bash
# 如果项目有 gradlew：
./gradlew assembleDebug

# 编译成功后 APK 通常位于：
app/build/outputs/apk/debug/app-debug.apk
```

如果想新建一个空项目，可先使用 Android Studio 在本地创建（GUI 更方便），或直接从 GitHub 上的模板克隆一个样例工程。

---

## 8️⃣ 将 APK 部署到设备或模拟器（可选）

- 真机（需开启 USB 调试）：
    

```bash
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

- 模拟器：需要安装 emulator 与系统镜像（`system-images`），并创建 AVD。命令行使用 `avdmanager` / `emulator`。
    

---

## 9️⃣ 常见问题 & 排查建议 ❗

- `sdkmanager` 找不到：确认 PATH 是否包含 `$ANDROID_HOME/cmdline-tools/latest/bin`。
    
- `java` 版本不对：Gradle/AGP 可能需要特定 JDK 版本，查看项目 `gradle.properties` / `build.gradle` 推荐的版本。
    
- 下载慢或失败：考虑使用代理或镜像（国内网络环境常见）。
    
- 权限问题：若在 `/opt` 等系统目录解压安装，需 `sudo`。
    

---

## 🔁 推荐一键脚本（示例）

下面给出一个**示例脚本**的框架（**请先审阅再运行**，并根据需要改版本号）：

```bash
#!/usr/bin/env bash
set -e

# 安装基础工具
sudo apt update
sudo apt install -y git unzip wget curl zip build-essential openjdk-17-jdk

# 目录
SDK_ROOT=$HOME/Android
mkdir -p $SDK_ROOT/cmdline-tools
cd $SDK_ROOT/cmdline-tools

# 下载命令行工具（请确认链接是否过期）
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O cmdline-tools.zip
unzip -o cmdline-tools.zip
mv cmdline-tools latest || true

# 环境变量（仅本次会话）
export ANDROID_HOME=$SDK_ROOT
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH

# 安装 SDK 组件
yes | sdkmanager --sdk_root=$ANDROID_HOME "platform-tools" "platforms;android-34" "build-tools;34.0.0"

echo "安装完成，请将下列行加入你的 ~/.bashrc 或 ~/.zshrc："
echo "export ANDROID_HOME=\$HOME/Android"
echo "export PATH=\$ANDROID_HOME/cmdline-tools/latest/bin:\$ANDROID_HOME/platform-tools:\$PATH"
```

---

## 🔗 参考 & 延伸阅读

- Android 官方开发者网站（SDK / command line tools）
    
- Gradle 官方文档
    
- Android NDK 文档（若使用原生 C/C++）
    

> 上面链接建议直接在浏览器打开 Android 官方站点获取最新版工具和镜像。

---

## ✅ 小结

在 Debian 12 上搭建 Android 原生构建环境的要点：

- 安装合适的 **JDK（推荐 17）**
    
- 下载并配置 **Android SDK command-line tools**，并通过 `sdkmanager` 安装 `platform-tools`、`platforms` 与 `build-tools`
    
- 使用项目自带的 **Gradle Wrapper (`gradlew`)** 进行构建，必要时可系统安装 Gradle
    
- 如需本地编译原生代码，记得安装 **NDK / CMake**
    

---