Android 开发环境搭建与 APK 编译指南（Ubuntu）

> 离线/手动安装 Android SDK、JDK 17、Gradle 到 /home/user/tools/，配置环境变量，APK 编译命名约定。

1. 目录规划

所有开发工具统一安装在 /home/user/tools/ 下：

/home/user/tools/
├── jdk-17/                   # JDK 17
├── android-sdk/              # Android SDK
│   ├── cmdline-tools/
│   ├── platforms/
│   ├── build-tools/
│   ├── platform-tools/
│   └── ...
├── gradle-8.x/               # Gradle
└── android-studio/           # Android Studio（可选）

2. JDK 17 安装

2.1 手动/离线安装

# 下载 JDK 17（根据架构选择 x64 或 aarch64）
# https://adoptium.net/download/
# 或 Oracle JDK: https://www.oracle.com/java/technologies/downloads/#java17

# 解压到 tools 目录

mkdir -p /home/user/tools

tar -xzf OpenJDK17U-jdk_x64_linux_hotspot_17.0.9_9.tar.gz -C /home/user/tools/

mv /home/user/tools/jdk-17.0.9+9 /home/user/tools/jdk-17

2.2 通过 apt 安装

sudo apt update
sudo apt install -y openjdk-17-jdk openjdk-17-jre
# apt 安装在 /usr/lib/jvm/java-17-openjdk-amd64/

2.3 验证安装

/home/user/tools/jdk-17/bin/java -version
# openjdk version "17.0.9" 2023-10-17
# OpenJDK Runtime Environment (build 17.0.9+9-Ubuntu-122.04)
# OpenJDK 64-Bit Server VM (build 17.0.9+9-Ubuntu-122.04, mixed mode, sharing)

3. Android SDK 安装

3.1 下载命令行工具

# 下载 cmdline-tools（最小化安装）
cd /tmp
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip

# 解压到标准路径

mkdir -p /home/user/tools/android-sdk/cmdline-tools

unzip commandlinetools-linux-11076708_latest.zip -d /home/user/tools/android-sdk/cmdline-tools/

mv /home/user/tools/android-sdk/cmdline-tools/cmdline-tools \

   /home/user/tools/android-sdk/cmdline-tools/latest

3.2 设置环境变量

export ANDROID_HOME=/home/user/tools/android-sdk
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
export PATH="$ANDROID_HOME/platform-tools:$PATH"
export PATH="$ANDROID_HOME/build-tools/34.0.0:$PATH"

3.3 安装 SDK 组件

# 接受许可
yes | sdkmanager --licenses --sdk_root=$ANDROID_HOME

# 安装基础组件

sdkmanager --sdk_root=$ANDROID_HOME \

  "platform-tools" \

  "platforms;android-34" \

  "build-tools;34.0.0" \

  "extras;android;m2repository" \

  "extras;google;m2repository"

# 安装其他 API 级别（按需）

sdkmanager --sdk_root=$ANDROID_HOME \

  "platforms;android-33" \

  "build-tools;33.0.2"

3.4 sdkmanager 常用命令

# 列出已安装和可用的包
sdkmanager --list --sdk_root=$ANDROID_HOME

# 查看已安装的包

sdkmanager --list --sdk_root=$ANDROID_HOME 2>/dev/null | grep -E '^[[:space:]]+installed'

# 更新所有已安装包

sdkmanager --update --sdk_root=$ANDROID_HOME

# 卸载某个包

sdkmanager --uninstall "platforms;android-32" --sdk_root=$ANDROID_HOME

3.5 AVD（模拟器）管理

# 安装 system image
sdkmanager --sdk_root=$ANDROID_HOME \
  "system-images;android-34;google_apis;x86_64"

# 安装 emulator

sdkmanager --sdk_root=$ANDROID_HOME "emulator"

# 创建 AVD

avdmanager create avd \

  -n "Pixel_6_API_34" \

  -k "system-images;android-34;google_apis;x86_64" \

  -d "pixel_6"

# 列出 AVD

avdmanager list avd

# 启动模拟器

$ANDROID_HOME/emulator/emulator -avd Pixel_6_API_34 &

# 删除 AVD

avdmanager delete avd -n Pixel_6_API_34

4. Gradle 安装

4.1 手动安装

# 下载 Gradle 8.x
cd /tmp
wget https://services.gradle.org/distributions/gradle-8.7-bin.zip
unzip gradle-8.7-bin.zip -d /home/user/tools/

4.2 环境变量

export GRADLE_HOME=/home/user/tools/gradle-8.7
export PATH="$GRADLE_HOME/bin:$PATH"

4.3 验证

gradle --version
# Gradle 8.7
# Build time:   2024-03-22 15:00:00 UTC
# Revision:     ...
# Kotlin:       1.9.22
# Groovy:       3.0.17
# JVM:          17.0.9

4.4 Gradle Wrapper

Android 项目通常自带 gradlew，不依赖系统 Gradle。但需要确保 JVM 可用：

# gradlew 会自动下载项目指定的 Gradle 版本
cd /home/user/work/MyApp
./gradlew --version    # 首次运行会下载 Gradle

5. 环境变量持久化

将以下内容追加到 /home/user/.bashrc：

# ========== Android 开发环境 ==========

# JDK 17

export JAVA_HOME=/home/user/tools/jdk-17

export PATH="$JAVA_HOME/bin:$PATH"

# Android SDK

export ANDROID_HOME=/home/user/tools/android-sdk

export ANDROID_SDK_ROOT=$ANDROID_HOME

export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

export PATH="$ANDROID_HOME/platform-tools:$PATH"

export PATH="$ANDROID_HOME/build-tools/34.0.0:$PATH"

# Gradle

export GRADLE_HOME=/home/user/tools/gradle-8.7

export PATH="$GRADLE_HOME/bin:$PATH"

# Gradle 用户目录（缓存依赖包）

export GRADLE_USER_HOME=/home/user/tools/.gradle

# Android SDK 代理（如有需要）

# export ANDROID_SDK_PROXY_HOST=proxy.company.com

# export ANDROID_SDK_PROXY_PORT=8080

应用配置：

source /home/user/.bashrc
# 验证
echo $JAVA_HOME
echo $ANDROID_HOME
echo $GRADLE_HOME

6. APK 编译流程

6.1 标准编译命令

cd /home/user/work/Android/FCam

# 清理 + Debug 构建

./gradlew clean assembleDebug

# Release 构建（需要签名）

./gradlew clean assembleRelease

6.2 输出位置

app/build/outputs/apk/
├── debug/
│   └── app-debug.apk
└── release/
    └── app-release.apk    (需配置签名后才有)

6.3 APK 命名约定

# 获取项目名（当前目录的最后一段）
APP_NAME=$(basename "$PWD")
# 示例：/home/user/work/Android/FCam → APP_NAME="FCam"

# 生成带时间戳的文件名

TIMESTAMP=$(date +%Y%m%d_%H%M%S)

APK_NAME="${APP_NAME}_${TIMESTAMP}.apk"

# 复制并重命名

cp app/build/outputs/apk/debug/app-debug.apk /tmp/${APK_NAME}

echo "APK output: /tmp/${APK_NAME}"

6.4 一键编译脚本

创建 /home/user/tools/build-apk.sh：

#!/bin/bash
set -e

THIS_DIR=$(pwd)

APP_NAME=$(basename "$THIS_DIR")

TIMESTAMP=$(date +%Y%m%d_%H%M%S)

echo "=== Building ${APP_NAME} at ${TIMESTAMP} ==="

# 设置 JDK

export JAVA_HOME=${JAVA_HOME:-/home/user/tools/jdk-17}

export PATH="$JAVA_HOME/bin:$PATH"

# 设置 Android SDK

export ANDROID_HOME=${ANDROID_HOME:-/home/user/tools/android-sdk}

export ANDROID_SDK_ROOT=$ANDROID_HOME

# Gradle 用户目录

export GRADLE_USER_HOME=${GRADLE_USER_HOME:-/home/user/tools/.gradle}

# 清理并构建

echo "[1/3] Cleaning..."

./gradlew clean --no-daemon 2>&1 | tail -5

echo "[2/3] Building Debug APK..."

./gradlew assembleDebug --no-daemon 2>&1 | tail -10

# 复制到 /tmp

DEBUG_APK="app/build/outputs/apk/debug/app-debug.apk"

if [ -f "$DEBUG_APK" ]; then

    OUTPUT="/tmp/${APP_NAME}_${TIMESTAMP}.apk"

    cp "$DEBUG_APK" "$OUTPUT"

    SIZE=$(du -h "$OUTPUT" | cut -f1)

    echo "[3/3] Done: $OUTPUT ($SIZE)"

else

    echo "ERROR: Build failed, no APK found at $DEBUG_APK"

    exit 1

fi

使用：

cd /home/user/work/Android/FCam
bash /home/user/tools/build-apk.sh
# 输出：/tmp/FCam_20260724_153000.apk

7. Gradle 依赖下载与代理

7.1 代理配置

如果网络受限需要代理，在 ~/.gradle/gradle.properties 中配置：

# HTTP 代理
systemProp.http.proxyHost=proxy.company.com
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=username
systemProp.http.proxyPassword=password

# HTTPS 代理

systemProp.https.proxyHost=proxy.company.com

systemProp.https.proxyPort=8080

systemProp.https.proxyUser=username

systemProp.https.proxyPassword=password

# 不走代理的地址

systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.local

7.2 国内镜像加速

# ~/.gradle/init.gradle
allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/google/' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        mavenCentral()
        google()
    }
}

7.3 Gradle 依赖缓存位置

# 默认缓存目录
ls ~/.gradle/caches/modules-2/files-2.1/

# 如果设置了 GRADLE_USER_HOME

ls /home/user/tools/.gradle/caches/modules-2/files-2.1/

7.4 离线模式

# 如果依赖已全部缓存，可启用离线模式
./gradlew assembleDebug --offline

# 或在 gradle.properties 中设置

# org.gradle.daemon=false

# org.gradle.offline=true

7.5 常见依赖问题

# 1. 检查网络连接
ping google.com

# 2. 清除缓存重试

rm -rf ~/.gradle/caches/

./gradlew assembleDebug

# 3. 检查 build.gradle 中的仓库 URL

# repositories { google(); mavenCentral() }

# 4. 如果使用代理，确认 gradle.properties 配置正确

cat ~/.gradle/gradle.properties

# 创建 local.properties 文件
echo "sdk.dir=/home/user/tools/android-sdk" > local.properties

# 或设置环境变量

export ANDROID_HOME=/home/user/tools/android-sdk

export ANDROID_SDK_ROOT=/home/user/tools/android-sdk

8. Android Studio 安装（可选）

# 下载 Android Studio
cd /tmp
wget https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2024.1.1.11/android-studio-2024.1.1.11-linux.tar.gz

# 解压

tar -xzf android-studio-2024.1.1.11-linux.tar.gz -C /home/user/tools/

mv /home/user/tools/android-studio /home/user/tools/android-studio-2024.1

# 创建桌面快捷方式

cat > /home/user/.local/share/applications/android-studio.desktop << 'EOF'

[Desktop Entry]

Name=Android Studio

Comment=Android IDE

Exec=/home/user/tools/android-studio-2024.1/bin/studio.sh

Icon=/home/user/tools/android-studio-2024.1/bin/studio.png

Type=Application

Categories=Development;IDE;

Terminal=false

EOF

# 启动

/home/user/tools/android-studio-2024.1/bin/studio.sh &

9. ADB 调试

9.1 连接设备

# 列出设备
adb devices

# USB 连接后确认授权

# 手机上会弹出"允许 USB 调试"对话框

# 无线调试（Android 11+）

adb pair <IP>:<pairing-port> <pairing-code>

adb connect <IP>:<connect-port>

9.2 常用 adb 命令

# 安装 APK
adb install /tmp/FCam_20260724_153000.apk

# 覆盖安装（保留数据）

adb install -r app.apk

# 卸载

adb uninstall com.example.fcam

# 查看日志

adb logcat -s MyAppTag

# 截图

adb shell screencap -p /sdcard/screen.png

adb pull /sdcard/screen.png .

# 录屏

adb shell screenrecord /sdcard/demo.mp4

# Ctrl+C 停止

adb pull /sdcard/demo.mp4 .

9.3 udev 规则（Linux USB 权限）

# 创建 udev 规则文件
sudo tee /etc/udev/rules.d/51-android.rules << 'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"
EOF

sudo udevadm control --reload-rules

sudo udevadm trigger

# 将用户加入 plugdev 组

sudo usermod -aG plugdev $USER

10. 完整安装检查清单

#!/bin/bash
# 保存为 /home/user/tools/check-android-env.sh

echo "=== Android Dev Environment Check ==="

# Java

echo -n "Java: "

java -version 2>&1 | head -1 || echo "NOT FOUND"

# Android SDK

echo -n "Android SDK: "

[ -d "$ANDROID_HOME" ] && echo "$ANDROID_HOME ($(ls $ANDROID_HOME/platforms/ 2>/dev/null))" || echo "NOT FOUND"

# SDK Manager

echo -n "sdkmanager: "

command -v sdkmanager &>/dev/null && echo "OK" || echo "NOT FOUND"

# Gradle

echo -n "Gradle: "

command -v gradle &>/dev/null && gradle --version 2>&1 | head -2 | tail -1 || echo "NOT FOUND"

# ADB

echo -n "ADB: "

command -v adb &>/dev/null && echo "$(adb --version | head -1)" || echo "NOT FOUND"

# 环境变量

echo ""

echo "JAVA_HOME       = $JAVA_HOME"

echo "ANDROID_HOME    = $ANDROID_HOME"

echo "GRADLE_HOME     = $GRADLE_HOME"

echo "GRADLE_USER_HOME = $GRADLE_USER_HOME"

echo ""

echo "=== Check Complete ==="

11. 参考链接

• Android Studio 下载
• SDK Platform 版本对照
• Gradle 官方文档
• Adoptium JDK 下载