在 Linux 上开发 Android，其实没有想象中那么难

很多人一提到 Android 开发，第一反应就是：

• 必须装 Android Studio
• 环境变量很烦
• SDK / JDK / Gradle 版本经常打架
• 模拟器重，真机调试麻烦
• Linux 上搞 Android 感觉像“民间偏方”

但我这次在 Linux 上把一个真实的 Android APK 项目跑通、修改、编译、安装，反而更加确信一件事：

Linux 完全可以作为 Android 的一线开发环境，而且命令行工作流其实很强。

这篇文章我尽量用“手工搭环境 + 命令行构建 + 真机调试”的方式讲清楚，适合：

• 想在 Linux 上做 Android 开发的人
• 想搭 CI / 自动化构建环境的人
• 不想一上来就被 Android Studio 全家桶绑住的人
• 想用 VS Code / Neovim / JetBrains Fleet 之类编辑器配合 Gradle 的人

这份指南也结合了一个真实项目验证过的流程：

• JDK: 17
• Android SDK Command-line Tools: 20.0
• Android Platform Tools: 37.0.0
• Android SDK Platform: android-36
• Build Tools: 36.0.0
• 构建方式: ./gradlew :app:assembleDebug

一、先把 Android 开发拆开看

Android 开发看起来复杂，本质上其实只需要理解 5 件事：

1. JDK：给 Gradle / Kotlin / Java 编译器用
2. Android SDK：给 Android 平台、构建工具、adb 用
3. Gradle Wrapper：项目自己的构建入口
4. 编辑器 / IDE：写代码的工具，可选 Android Studio，也可以不用
5. 设备或模拟器：用来安装和调试 APK

换句话说，Android Studio 只是把这些东西打包得更完整，但不是唯一入口。

如果你已经有：

• 一个正常的 Linux 开发环境
• 一台 Android 真机
• 一个带 gradlew 的 Android 项目

那你离能编译 APK，其实已经不远了。

二、Linux 上最小可用环境

下面以 Ubuntu / Debian 系为例。

1. 安装 JDK 和基础工具

bash
展开代码
sudo apt update
sudo apt install -y openjdk-17-jdk unzip zip wget curl git

检查 JDK：

bash
展开代码
java -version
javac -version

如果项目使用的是较新的 Android Gradle Plugin，JDK 17 基本已经是当前最稳妥的选择。

如果你机器上装了多个 JDK，建议显式设置：

bash
展开代码
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

不同发行版的 JDK 路径可能不同，可以这样查：

bash
展开代码
readlink -f $(which java)

三、安装 Android SDK Command-line Tools

Android 官方已经明确支持不装 Android Studio，只安装命令行工具的方式开发和构建 Android。这个方式尤其适合 Linux、服务器和 CI。

1. 选择一个 SDK 安装目录

比如：

bash
展开代码
mkdir -p $HOME/android-sdk

2. 下载 Command-line Tools

去 Android 官方下载页下载 Command line tools for Linux：

• https://developer.android.com/studio
• https://developer.android.com/tools/sdkmanager

下载完成后解压，并整理成 Android 官方推荐的目录结构：

bash
展开代码
mkdir -p $HOME/android-sdk/cmdline-tools
cd /tmp
unzip commandlinetools-linux-*.zip
mv cmdline-tools $HOME/android-sdk/cmdline-tools/latest

最终建议目录长这样：

text
展开代码
$HOME/android-sdk/
├── cmdline-tools/
│   └── latest/
│       ├── bin/
│       ├── lib/
│       └── source.properties

3. 配置环境变量

把下面这些内容写进 ~/.bashrc 或 ~/.zshrc：

bash
展开代码
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

生效：

bash
展开代码
source ~/.bashrc

检查：

bash
展开代码
sdkmanager --version
adb version

四、安装 Android 平台和构建工具

Command-line Tools 本身只是一把钥匙，真正构建项目时还需要平台包和 build-tools。

先接受许可证：

bash
展开代码
yes | sdkmanager --licenses

然后安装常用组件：

bash
展开代码
sdkmanager --install \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "cmdline-tools;latest"

如果你项目的 compileSdk 是别的版本，比如 34 或 35，就把 platforms;android-36 改掉。

如何知道项目需要什么版本？

直接看模块的 build.gradle.kts 或 build.gradle：

kotlin
展开代码
android {
    compileSdk = 36

    defaultConfig {
        minSdk = 33
        targetSdk = 36
    }
}

如果项目声明了：

• compileSdk = 36
• targetSdk = 36

那你至少要装：

• platforms;android-36
• 一套可用的 build-tools

五、为什么我强烈建议用项目自带的 gradlew

很多 Android 新手会直接装一个系统级 gradle，然后执行：

bash
展开代码
gradle build

这通常不是最稳的做法。

更推荐使用项目自带的 gradlew，因为：

• 它会使用项目锁定的 Gradle 版本
• 团队成员环境更一致
• CI 也通常这样跑
• 少掉很多“我这里能编，你那里不能编”的问题

也就是说，进入项目目录后，优先执行：

bash
展开代码
./gradlew tasks

而不是直接使用系统的 gradle。

六、一个真实 Android 项目的 Linux 构建流程

假设项目目录是：

text
展开代码
pipecat_apps/livekit_video_chat_apk/

这个目录里有：

• gradlew
• settings.gradle.kts
• app/

那么最常用的命令就是：

bash
展开代码
cd pipecat_apps/livekit_video_chat_apk
export ANDROID_HOME=/opt/android-sdk
export ANDROID_SDK_ROOT=/opt/android-sdk
./gradlew :app:compileDebugKotlin
./gradlew :app:assembleDebug

如果构建成功，APK 通常在：

text
展开代码
app/build/outputs/apk/debug/app-debug.apk

这两个命令分别做什么？

1. 先跑 Kotlin 编译

bash
展开代码
./gradlew :app:compileDebugKotlin

作用：

• 先验证 Kotlin / Compose / 依赖是否能过编译
• 比直接全量打包更快
• 很适合作为“第一道烟雾测试”

2. 再打完整 APK

bash
展开代码
./gradlew :app:assembleDebug

作用：

• 生成 debug APK
• 适合本地安装和真机测试

七、如何在 Linux 上安装 APK 到手机

我个人非常推荐：Linux + 真机 + adb。

因为很多时候，真机比模拟器更省心：

• 麦克风 / 摄像头 / 蓝牙 / 网络环境更真实
• 性能更稳定
• 少掉模拟器图形和硬件加速问题

1. 打开手机开发者选项

在 Android 手机上：

• 连续点击版本号，打开开发者模式
• 打开 USB 调试
• 用数据线连到 Linux 机器

2. 检查设备连接

bash
展开代码
adb devices

如果第一次连接，手机会弹授权框，点允许。

看到类似输出就说明连上了：

text
展开代码
List of devices attached
XXXXXXXXXXXX    device

3. 安装 APK

bash
展开代码
adb install -r app/build/outputs/apk/debug/app-debug.apk

说明：

• -r 表示覆盖安装
• 这对频繁调试非常有用

如果你知道应用包名，也可以直接启动：

bash
展开代码
adb shell am start -n com.zhiyue.livekitvideochatapk/.MainActivity

八、Linux 上调 Android 日志，其实很好用

很多人只在 Android Studio 里看 Logcat，但 Linux 终端下调日志其实非常顺手。

1. 直接看全部日志

bash
展开代码
adb logcat

2. 先清空再看

bash
展开代码
adb logcat -c
adb logcat

3. 配合 rg 过滤关键词

bash
展开代码
adb logcat | rg "AndroidRuntime|FATAL|LiveKit|OkHttp|zhiyue"

这个组合在 Linux 上特别强：

• adb logcat 输出系统日志
• rg 做高性能筛选
• 出现崩溃时几乎可以秒定位

4. 看崩溃最有用的几个关键词

你可以重点关注：

• AndroidRuntime
• FATAL EXCEPTION
• SecurityException
• NetworkSecurityConfig
• IllegalStateException
• NullPointerException

九、如果你还想用模拟器，也完全可以

如果你没有真机，也可以在 Linux 上用模拟器，只是通常更重一些。

先安装：

bash
展开代码
sdkmanager --install \
  "emulator" \
  "platform-tools" \
  "platforms;android-36" \
  "system-images;android-36;google_apis;x86_64"

创建 AVD：

bash
展开代码
avdmanager create avd -n pixel-api-36 \
  -k "system-images;android-36;google_apis;x86_64"

启动模拟器：

bash
展开代码
emulator -avd pixel-api-36

不过，如果你的项目涉及：

• 摄像头
• 麦克风
• WebRTC / LiveKit
• 音视频实时交互
• 蓝牙 / 通话 / 系统悬浮窗

我还是建议优先真机。

十、Linux 上开发 Android，最常见的坑

1. ./gradlew: No such file or directory

原因通常很简单：你不在 Android 项目的根目录。

比如要进到这个目录：

bash
展开代码
cd pipecat_apps/livekit_video_chat_apk

再执行：

bash
展开代码
./gradlew :app:assembleDebug

2. SDK location not found

说明 Gradle 没找到 Android SDK。

检查：

bash
展开代码
echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT

必要时显式设置：

bash
展开代码
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME

3. failed to find Build Tools revision

说明缺少对应 build-tools。

解决：

bash
展开代码
sdkmanager --install "build-tools;36.0.0"

按项目实际版本替换即可。

4. Platform android-XX not found

说明缺少平台包。

解决：

bash
展开代码
sdkmanager --install "platforms;android-36"

5. JDK 版本不对

如果项目要求 JDK 17，而你机器默认还是 11 或 21，Gradle 可能会报莫名其妙的问题。

建议：

bash
展开代码
java -version
./gradlew --version

优先保证项目和本机 JDK 主版本一致。

6. adb devices 看不到手机

Linux 下这很常见，通常有几种原因：

• 数据线只是充电线
• 手机上没开 USB 调试
• 没点设备授权弹窗
• Linux 没配好 udev 规则

先试：

bash
展开代码
adb kill-server
adb start-server
adb devices

如果还是不行，再去补设备厂商的 udev 规则。

7. 10.0.2.2 只对模拟器有效

这是非常高频的坑。

• Android 模拟器访问宿主机回环地址：用 10.0.2.2
• 真机访问宿主机服务：不能用 10.0.2.2
• 真机应该用：
  • 局域网 IP
  • 公网 IP
  • 或正式域名

8. WebSocket / HTTP 明明服务是通的，App 却连不上

常见原因：

• 地址填错了端口
• 你在真机上还写着 localhost
• ws:// 和 wss:// 混用了
• App 没配置 cleartext HTTP
• 服务端证书或反向代理没配好

Android 联网问题，七成不是代码，而是地址和网络边界。

十一、Linux 命令行工作流，为什么反而更适合工程化

很多人觉得 Android Studio 才是“正统”，但如果你从工程效率角度看，Linux 命令行其实有很大优势。

1. 更容易自动化

比如你可以很自然地串起来：

bash
展开代码
./gradlew :app:compileDebugKotlin && \
./gradlew :app:assembleDebug && \
adb install -r app/build/outputs/apk/debug/app-debug.apk

2. 更适合 CI / 远程开发

在服务器、远程工作站、容器、云开发机上，CLI 方案比 GUI 方案稳定得多。

3. 更适合和 AI 编码助手协作

当项目能通过：

• 读源码
• 跑 Gradle
• 看 logcat
• 直接构建 APK

形成完整闭环时，AI 其实能帮你做非常多事情。

4. 出问题时更透明

终端日志、Gradle 任务、依赖下载过程、打包路径，都更直接。

你不会只看到一个 IDE 弹窗写着：

text
展开代码
Build failed

而是能看到具体失败在哪个 task、哪个依赖、哪个源码文件。

十二、什么时候还是建议装 Android Studio

虽然我一直在强调 Linux CLI 工作流很好，但我并不反对 Android Studio。

如果你要做这些事情，Android Studio 依然很有价值：

• Compose Preview
• Layout Inspector
• Profiler
• 数据库查看器
• Manifest / Gradle 可视化编辑
• 模拟器图形化管理

我的建议是：

• 构建、安装、调试链路：尽量学会 CLI
• 复杂 UI 调整、性能分析：再结合 Android Studio

这样你的工作流最灵活。

十三、一套我自己比较推荐的 Linux Android 开发习惯

如果你问我，Linux 上开发 Android，最舒服的姿势是什么，我会推荐这套：

1. 用 JDK 17
2. Android SDK 用 command-line tools 安装
3. 永远优先用项目自带 ./gradlew
4. 真机优先，模拟器次之
5. 用 adb logcat | rg 看日志
6. 编辑器随意，但构建和安装尽量脚本化
7. 把常用命令写到 Makefile、justfile 或 shell script

比如：

bash
展开代码
#!/usr/bin/env bash
set -e

export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME

./gradlew :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

你会发现，一旦链路打通，Android 在 Linux 上并不“麻烦”，反而是非常适合工程化和自动化的一类开发工作。

十四、这篇文章最后想说的

Android 开发真正难的，不是 Linux。

真正难的是：

• 你第一次接触时，概念太多
• IDE 把很多细节藏起来了
• 出错时不知道是 JDK、SDK、Gradle、设备，还是网络问题

一旦你把它拆开，Android 在 Linux 上其实很清晰：

• JDK 负责编译器
• SDK 负责 Android 平台工具
• Gradle Wrapper 负责项目构建
• adb 负责设备通信
• 编辑器只是编辑器

搞明白这一层以后，你会发现：

Linux 不但能开发 Android，而且非常适合认真做 Android。

---

附：一套最小可用命令速查

安装依赖

bash
展开代码
sudo apt update
sudo apt install -y openjdk-17-jdk unzip zip wget curl git

环境变量

bash
展开代码
export ANDROID_HOME=$HOME/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

安装 SDK 组件

bash
展开代码
yes | sdkmanager --licenses
sdkmanager --install \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "cmdline-tools;latest"

构建 APK

bash
展开代码
cd pipecat_apps/livekit_video_chat_apk
./gradlew :app:compileDebugKotlin
./gradlew :app:assembleDebug

安装到手机

bash
展开代码
adb devices
adb install -r app/build/outputs/apk/debug/app-debug.apk

看日志

bash
展开代码
adb logcat -c
adb logcat | rg "AndroidRuntime|FATAL|LiveKit|OkHttp"

---

参考资料

• Android SDK Command-line Tools / sdkmanager
  • https://developer.android.com/tools/sdkmanager
• Android Studio 下载页
  • https://developer.android.com/studio
• ADB 官方文档
  • https://developer.android.com/guide/developing/tools/adb.html
• Android Studio 安装说明
  • https://developer.android.com/studio/install