# 在 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

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

fishspeech 2 tts

不换模型，先换“马具系统”：Harness Engineering 如何让 AI Agent 从乱跑到稳驾

要么这样：
```bash
adb -s 582QUGHE22746 reboot fastboot
fastboot -s 582QUGHE22746 reboot fastboot
# 刷镜像命令
fastboot -s 582QUGHE22746 flash logo logo.img
fastboot -s 582QUGHE22746 flash system system.img
fastboot -s 582QUGHE22746 flash system_ext system_ext.img
fastboot -s 582QUGHE22746 flash product product.img
fastboot -s 582QUGHE22746 flash pvmfw pvmfw.img
fastboot -s 582QUGHE22746 flash vbmeta_system vbmeta_system.img
fastboot -s 582QUGHE22746 -w
fastboot -s 582QUGHE22746 reboot
```


要么这样：
```bash
adb -s 582QUGHE22746 reboot fastboot
fastboot -s 582QUGHE22746 reboot fastboot
# 刷镜像命令
fastboot flash logo logo.img
fastboot -w flashall
fastboot reboot
```

Android 开发刷机指令

FireRedTTS2 streaming Docker 流式 TTS 服务


# LiveKit Server 安装指南 (Linux x86_64)

## 前提确认
*   操作系统: Linux
*   架构: x86_64
*   当前状态: 未安装 `livekit-server`

## 安装方法 (官方推荐)
最直接的安装方式是使用官方提供的安装脚本。

### 标准安装 (需要 `sudo` 权限)
```bash
curl -sSL https://get.livekit.io | bash
```

### 用户目录安装 (无需 `sudo` 权限)
如果无法写入系统目录 (`/usr/local/bin`)，可安装到当前用户目录：
```bash
mkdir -p ~/.local/bin
INSTALL_PATH=$HOME/.local/bin curl -sSL https://get.livekit.io | bash
export PATH="$HOME/.local/bin:$PATH"
```

## 验证安装
安装完成后，验证命令是否可用：
```bash
livekit-server --version
```

## 启动服务器 (开发模式)
要启动一个监听所有网卡 (`0.0.0.0`) 的开发服务器：
```bash
livekit-server --dev --bind 0.0.0.0
```
**开发模式默认凭据:**
*   **API Key:** `devkey`
*   **API Secret:** `secret`

## 重要提醒
1.  **网络访问**: 如果希望其他设备能够访问此服务器，请确保防火墙/安全组已开放 **7880** 端口。
2.  **路径持久化**: 如果使用用户目录安装，建议将 `export PATH="$HOME/.local/bin:$PATH"` 添加到你的 Shell 配置文件 (如 `~/.bashrc` 或 `~/.zshrc`) 中，使其永久生效。

## 参考链接
*   https://docs.livekit.io/transport/self-hosting/local/
*   https://get.livekit.io/




```bash
  docker run -d --name livekit \
    --restart unless-stopped \
    -p 7880:7880/tcp \
    -p 7881:7881/tcp \
    -p 7882:7882/udp \
    -e LIVEKIT_KEYS="devkey: secret" \
    livekit/livekit-server:latest \
    --dev \
    --bind 0.0.0.0 \
    --node-ip <你的服务器公网IP>
```


  - 7882 必须按 udp 映射，也就是 -p 7882:7882/udp
  - 不能只写 -p 7882:7882，那样 Docker 默认按 TCP 处理，WebRTC 媒体大概率会出问题

  为什么是 3 个端口，不是 1 个端口就完事？

  - 7880：信令和 API。客户端先通过 WebSocket 连这个端口，完成鉴权、进房、交换协商信息。
  - 7882/udp：真正的 WebRTC 媒体主通道。音视频数据优先走这里，延迟最低。LiveKit 官方把它叫 ICE/UDP Mux，意思是“把所有 UDP 媒体流复用到一个 UDP 端口上”，这已经是“简化
    版”了，否则默认还可能用一大段 UDP 端口范围。
  - 7881/tcp：UDP 不通时的兜底通道。比如公司网络、VPN、运营商环境把 UDP 卡掉了，客户端还能尝试走 ICE/TCP。




LiveKit Server 安装指南 (Linux x86_64)

dockerfile里安装：

```bash
# 安装 Node.js 和 npm
RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm

# 安装 codex
RUN npm install -g @openai/codex
```

