第4章：CI环境搭建 — 配置服务器、JDK、Gradle、Android SDK
搭建CI环境，说白了就是给自动化流水线准备好"地基"。地基没打牢，后面排查AGP兼容性问题时会不断踩坑。
我见过不少团队，环境装得乱七八糟，最后定位问题花了几天时间。其实只需要把几个关键步骤理清楚，后面会省很多事。
核心原则：保持环境干净、版本可控、路径统一。
4.1 选择合适的CI服务器
常见方案就那几种：Jenkins、GitLab CI、GitHub Actions、CircleCI。我自己的习惯是优先用Jenkins，因为自托管、插件生态成熟，排查AGP问题时能拿到最完整的日志。
如果你团队用GitLab，直接用GitLab Runner也挺省事。关键点只有一个：你手上有CI服务器的root权限或sudo权限，后续安装软件才方便。
| 服务器类型 | 优点 | 缺点 |
|---|---|---|
| Jenkins | 插件丰富、完全可控 | 维护成本略高、界面老旧 |
| GitLab CI | 与代码库集成紧密 | 自定义较麻烦 |
| GitHub Actions | 托管、免运维 | 日志保留时间短 |
| CircleCI | 速度优化好 | 免费额度有限 |
我的经验：局域网内用Jenkins最靠谱。有一次客户的CI环境在私有云上，无法访问外网，GitHub Actions直接废了，最后还是Jenkins+离线插件搞定。
4.2 安装JDK
JDK是Android构建的基础。AGP和Gradle都需要它。千万别装JRE，必须装JDK。
警告：Android Gradle Plugin 7.x+ 要求 JDK 11，AGP 8.x 要求 JDK 17。一定要看官方兼容表，否则构建会报奇怪错误。
安装步骤（以Ubuntu为例）：
# 添加openjdk仓库（可选）
sudo apt update
sudo apt install openjdk-17-jdk -y
# 验证
java -version
# 输出应含 "openjdk version "17""
# 设置JAVA_HOME（重要！）
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
我建议把环境变量写入 /etc/environment 或 ~/.bashrc，这样每次重启不会丢。
4.3 安装Gradle
你可以用系统级安装，也可以用Gradle Wrapper。我的建议：在CI上统一安装一个稳定版本的Gradle，然后用项目自带的 gradlew 调用它。
# 下载 & 解压
wget https://services.gradle.org/distributions/gradle-8.4-bin.zip
sudo unzip -d /opt/gradle gradle-8.4-bin.zip
# 配置环境变量
export GRADLE_HOME=/opt/gradle/gradle-8.4
export PATH=$GRADLE_HOME/bin:$PATH
# 验证
gradle -v
重要：AGP版本与Gradle版本有严格的对应关系。例如AGP 8.2要求Gradle 8.2+。版本不匹配是CI上最常见的AGP兼容性问题之一。
4.4 安装Android SDK
这一块坑最多。我见过不少同事直接安装Android Studio然后复制SDK，结果CI环境里一堆权限问题。最好用命令行工具（sdkmanager）静默安装。
# 1. 下载command line tools（仅需一次）
wget https://dl.google.com/android/repository/commandlinetools-linux-10406996_latest.zip
unzip -d ~/android-sdk commandlinetools-linux-*.zip
# 2. 移动到标准位置（可选）
mkdir -p $HOME/android-sdk/cmdline-tools
mv cmdline-tools $HOME/android-sdk/cmdline-tools/latest
# 3. 接受许可 & 安装必需的包
export ANDROID_HOME=$HOME/android-sdk
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager \
"platforms;android-34" \
"build-tools;34.0.0" \
"ndk;25.2.9519653" # 按需
# 4. 验证
$ANDROID_HOME/platform-tools/adb --version
| SDK组件 | 用途 | 最小版本建议 |
|---|---|---|
| platforms;android-34 | 编译目标API | 项目targetSdkVersion |
| build-tools;34.0.0 | 构建工具 | ≥33.0.0 |
| ndk;25.2.9519653 | 原生代码编译 | 看项目需要 |
| cmdline-tools | sdkmanager本体 | 最新版 |
4.5 配置环境变量（关键决策）
很多AGP问题都出在环境变量没设对。记住三个必设变量：JAVA_HOME、ANDROID_HOME、GRADLE_HOME（可选，但建议设）。
我习惯把配置集中放在一个文件里，比如 /etc/profile.d/android.sh，便于管理和排查。
# /etc/profile.d/android.sh
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export ANDROID_HOME=/home/ubuntu/android-sdk
export GRADLE_HOME=/opt/gradle/gradle-8.4
export PATH=$JAVA_HOME/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$GRADLE_HOME/bin:$PATH
注意：ANDROID_HOME不能包含空格或中文，否则sdkmanager直接报错。Windows CI上这个问题更常见，Linux基本没问题。
4.6 验证构建
环境装完后，我建议立刻跑一个简单的Android项目验证。别等正式构建时才发现少了个包。
git clone https://github.com/某个简单Android项目.git
cd 项目目录
export ANDROID_HOME=... # 或者已写入环境变量
./gradlew assembleDebug
# 期望输出：BUILD SUCCESSFUL in Xs
避坑指南：我曾经遇到一个项目，CI上本地构建能过，但CI服务器一直报“找不到platforms”。最后发现是ANDROID_HOME指向了错误的目录，而且没有把sdkmanager安装的platforms同步到该目录。建议用
sdkmanager --list 确认安装状态。
4.7 常见问题与检查清单
- 问题1：Gradle一直下载依赖超时 → 检查网络，CI服务器能否访问maven.google.com/jcenter？最好配国内镜像或公司内部Nexus。
- 问题2：AGP版本与Gradle版本不匹配 → 参照官方文档，锁定major版本号。
- 问题3：找不到android.jar → ANDROID_HOME未设置或platforms未安装。
- 问题4：JAVA_HOME指向JRE而非JDK → 重新安装JDK并设对路径。
最终检查清单：
- ☐ 服务器：Linux / macOS / Windows（建议Linux）
- ☐ JDK：版本匹配AGP要求
- ☐ Gradle：版本不低于AGP要求
- ☐ Android SDK：platforms + build-tools 正确安装
- ☐ 环境变量：JAVA_HOME, ANDROID_HOME, PATH 均生效
- ☐ 权限：CI用户有读写SDK目录的权限
- ☐ 验证：gradlew assembleDebug 至少成功一次