Linux系统安装配置Android SDK命令行工具完整指南

1. 项目背景与核心价值

如果你在Ubuntu或者任何Linux发行版上折腾过Android开发，尤其是想用命令行工具（commandlinetools）来管理SDK，大概率会遇到一堆让人头疼的问题。官方文档写得像天书，社区教程版本过时，照着做不是这里报错就是那里缺文件。我自己在给团队搭建CI/CD环境、配置无头（Headless）构建服务器，或者只是想在一个干净的Linux系统上快速搭建Android编译环境时，踩遍了所有的坑。今天这篇内容，就是把我这些年反复验证、最稳定可靠的安装和配置流程，结合最新的工具变化，完整地梳理出来。

核心要解决的问题很简单：在Linux系统上，如何正确、完整地安装Android SDK，特别是其命令行管理工具sdkmanager，并配置好环境，让它能稳定地下载平台工具、构建工具和各种API级别的SDK包。这不仅是个人开发者的需求，更是自动化构建、持续集成场景下的刚需。一个配置不当的环境，轻则编译失败，重则浪费大量排查时间。本文会从系统准备开始，一步步带你走过安装、配置、验证的全过程，并重点解释每个步骤背后的逻辑，以及那些官方文档里不会写的“坑点”。

2. 环境准备与关键概念澄清

在开始下载和安装之前，有几件事必须提前理清，这能避免你走上弯路。很多人安装失败，根源就在于对Android SDK现有的发布结构和依赖关系理解有误。

2.1 系统环境与包管理

首先，确保你的Ubuntu或其他Linux发行版是较新的版本。我以Ubuntu 22.04 LTS或24.04 LTS作为基准环境，因为它们拥有较新的软件库和稳定的内核。使用以下命令更新系统包列表并升级现有软件是一个好习惯：

sudo apt update && sudo apt upgrade -y

接下来，我们需要安装一些基础依赖。Java开发工具包（JDK）是编译Android应用的基石。Google官方推荐使用OpenJDK。对于目前主流的Android开发（包括Android Gradle Plugin 8.0+），需要JDK 17。安装命令如下：

sudo apt install openjdk-17-jdk -y

安装完成后，验证Java版本：

java -version

你应该看到类似“openjdk version “17.0.11” 2024-04-16”的输出。如果系统里存在多个Java版本，你可能需要配置默认版本，可以使用sudo update-alternatives --config java进行选择。

除了JDK，还有一些通用工具和库需要安装，比如用于解压文件的unzip，以及一些32位兼容库（某些旧的Android工具可能需要）。执行以下命令一并安装：

sudo apt install unzip curl wget libc6-i386 libncurses5 lib32z1 libstdc++6 -y

2.2 理解Android SDK的现代结构：告别“android”命令

这是一个至关重要的认知转变。如果你搜索的教程里还在让你下载一个巨大的“android-sdk”压缩包，或者教你使用android命令来更新SDK，那么这份教程已经过时至少5年了。

Google早已将Android SDK的图形化管理工具（即旧的SDK Manager GUI）和android命令行工具废弃。现在的核心是命令行工具包（Command-line Tools），它是一个独立的、轻量级的zip文件，里面最主要的就是sdkmanager这个命令行程序。sdkmanager是你与Android SDK组件仓库交互的唯一官方命令行接口。你需要用它来下载你真正需要的东西：平台SDK（如Android 14）、构建工具（如Build-Tools 34.0.0）、系统镜像、平台工具（如adb, fastboot）等。

因此，我们的安装思路是：先获取最小的命令行工具包，然后用它来“引导”安装完整的SDK组件。这种模块化的方式更灵活，特别适合服务器和无头环境。

2.3 规划安装目录

不建议使用系统级的目录如/usr/local/android-sdk，因为这通常需要root权限，后续更新和管理不便。更推荐的做法是在你的用户主目录下创建一个专属目录。我个人的习惯是~/Android/Sdk，这个路径也与Android Studio的默认路径一致，便于统一管理。

mkdir -p ~/Android/Sdk

这个Sdk目录（注意大写S）将作为我们整个Android SDK的根目录。

3. 下载与安装命令行工具包

现在进入实操阶段。我们将从Google的官方仓库下载命令行工具包。

3.1 获取正确的下载链接

官方下载页面地址是：https://developer.android.com/studio#command-tools。但更直接的方式是，我们通过命令行获取最新的稳定版本。你可以打开浏览器查看页面，找到Linux平台的下载链接。或者，使用wget或curl直接下载。为了确保我们获取的是最新版，最好去官网核对一次。

截至撰写时，命令行工具包的命名规则通常是commandlinetools-linux-<版本号>_latest.zip。我们将其下载到临时目录，比如~/Downloads。

cd ~/Downloads # 示例链接，请替换为官网最新的实际链接 wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip

注意：上面的版本号11076708是举例，务必去官网复制最新的链接。下载速度可能较慢，可以考虑使用代理或寻找国内镜像源。

3.2 解压到SDK根目录的正确位置

这是最容易出错的一步。解压后的文件夹结构必须放置在一个特定的子目录下，sdkmanager才能正常工作。压缩包内通常是一个名为cmdline-tools的目录。

我们需要在SDK根目录下创建一个cmdline-tools目录，然后将解压出来的内容放入其下的latest子目录中。这是sdkmanager期望的路径结构。

# 创建目标目录结构 mkdir -p ~/Android/Sdk/cmdline-tools/latest # 解压到临时目录 unzip commandlinetools-linux-*.zip -d /tmp/android-cmdline-tools # 查看解压出的内容，通常是一个`cmdline-tools`文件夹 ls /tmp/android-cmdline-tools # 将解压出的所有内容移动到我们创建好的`latest`目录下 # 注意：这里使用`mv`命令，并利用通配符`*`移动所有文件和子目录 mv /tmp/android-cmdline-tools/cmdline-tools/* ~/Android/Sdk/cmdline-tools/latest/ # 清理临时文件 rm -rf /tmp/android-cmdline-tools

现在，你的目录结构应该是这样的：

~/Android/Sdk/ └── cmdline-tools └── latest ├── bin │ ├── sdkmanager │ └── ... ├── lib └── ...

sdkmanager的可执行文件路径是~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager。

3.3 配置环境变量PATH

为了能在终端任何地方直接使用sdkmanager命令，需要将其所在目录添加到系统的PATH环境变量中。同时，我们还需要设置ANDROID_HOME或ANDROID_SDK_ROOT环境变量，许多构建工具（如Gradle）会依赖这个变量来定位SDK。

最持久的方法是修改shell的配置文件。如果你使用的是bash（默认），编辑~/.bashrc文件；如果使用zsh，则编辑~/.zshrc。

# 使用文本编辑器打开配置文件，例如nano nano ~/.bashrc

在文件的末尾添加以下几行：

# 设置Android SDK根目录 export ANDROID_SDK_ROOT=$HOME/Android/Sdk # 将命令行工具和平台工具的bin目录加入PATH export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/platform-tools

• ANDROID_SDK_ROOT: 明确指向SDK的根目录，这是现在推荐的方式（ANDROID_HOME已逐渐被弃用）。
• PATH: 添加了两个路径。第一个是sdkmanager的路径，第二个是platform-tools的路径（里面包含adb和fastboot，这个目录稍后我们会用sdkmanager安装）。

保存并退出编辑器（在nano中是Ctrl+X，然后按Y确认，再按Enter）。让配置立即生效：

source ~/.bashrc

现在，验证sdkmanager是否可以运行：

sdkmanager --version

如果输出类似10.0这样的版本号，恭喜你，命令行工具安装成功了。如果提示“命令未找到”，请检查：

1. 路径是否正确，特别是latest目录层级。
2. 是否执行了source ~/.bashrc。
3. 是否在同一个终端会话中。

4. 使用sdkmanager安装核心SDK组件

有了sdkmanager，我们就可以像“点菜”一样安装所需的SDK组件了。首先，查看有哪些可用的软件包列表。

4.1 列出可用与已安装的包

sdkmanager --list

这个命令会输出一个非常长的列表，包含了所有可用的平台、构建工具、系统镜像、附加组件等。输出分为几个部分：“Installed packages”和“Available Packages”。

初次运行，你可能会看到一个警告，提示你尚未接受任何许可协议。我们需要先接受许可。

4.2 接受必要的许可协议

在安装任何组件之前，必须接受Google的许可协议。你可以通过以下命令一次性接受所有未决的许可：

yes | sdkmanager --licenses

这个命令会列出所有需要接受的许可证，并自动输入y进行确认。如果自动确认失败，你也可以去掉yes |部分，手动对每个提示输入y。

4.3 安装核心必备组件

对于基础的Android编译环境，以下几个组件是必须的：

1. 平台工具（platform-tools）: 包含adb（调试桥）、fastboot等基础工具。
2. 构建工具（build-tools）: 包含将源代码编译成APK的工具，如aapt、dx（现已被D8/R8取代）、zipalign等。你需要选择与你的项目Gradle配置匹配的版本。
3. 平台SDK（platforms）: 对应特定Android API级别的SDK，包含框架库、系统资源等。你需要安装你应用所targetSdkVersion指定的平台。
4. 命令行工具更新（cmdline-tools）: 是的，命令行工具本身也可以通过sdkmanager更新到其他版本。

假设我们要安装当前常用的版本，命令如下：

sdkmanager “platform-tools” “platforms;android-34” “build-tools;34.0.0”

命令格式解析：

• 组件名称需要用引号括起来，特别是包含分号;的时候。
• platforms;android-34表示安装Android API 34（Android 14）的平台SDK。
• build-tools;34.0.0表示安装34.0.0版本的构建工具。

sdkmanager会开始下载并安装这些组件。所有组件都将被安装到ANDROID_SDK_ROOT目录下对应的子文件夹中。例如，platform-tools会安装到~/Android/Sdk/platform-tools，这正是我们之前添加到PATH中的路径。

4.4 验证安装结果

安装完成后，再次运行sdkmanager --list，你应该能在“Installed packages”部分看到刚才安装的组件。

同时，可以测试一下adb命令是否可用：

adb --version

如果输出了Android Debug Bridge的版本信息，说明platform-tools安装成功且环境变量配置正确。

5. 高级配置、问题排查与优化

基础环境搭好了，但在实际使用，尤其是自动化场景下，还会遇到一些深层次的问题。

5.1 镜像源配置以加速下载

由于网络原因，从Google官方仓库下载可能非常缓慢甚至失败。我们可以将sdkmanager的仓库源替换为国内镜像。清华大学和腾讯云都提供了不错的镜像。

这需要通过sdkmanager的--sdk_root参数和修改仓库配置文件来实现，但更一劳永逸的方法是直接设置环境变量。在~/.bashrc中，在Android SDK相关配置后面，添加以下内容：

# 使用清华大学镜像加速Android SDK下载 export SDKMANAGER_OPTS=”—no_https —proxy=http —proxy_host=mirrors.tuna.tsinghua.edu.cn —proxy_port=80"

但是，请注意，较新版本的sdkmanager对镜像的支持方式可能变化。另一种可靠的方法是，在调用sdkmanager时显式指定镜像站点的URL，但这需要修改sdkmanager的脚本或使用包装脚本，比较复杂。

更常见的实践是，在无法加速的情况下，直接使用代理或选择网络状况良好的时段进行首次安装。对于CI/CD环境，可以考虑将安装好的SDK目录打包缓存，避免每次构建都重新下载。

5.2 常见错误与解决方案

错误1:Warning: Could not create settings或java.io.IOException: Cannot run program “...”这通常是因为没有在cmdline-tools/latest这个特定路径下安装命令行工具。请严格按照第3.2节的目录结构进行检查和调整。

错误2:Failed to install the following Android SDK packages as some licences have not been accepted.即使你之前运行过yes | sdkmanager --licenses，在某些情况下许可协议可能仍未完全接受。可以尝试：

• 手动运行sdkmanager --licenses，仔细查看并逐一输入y。
• 检查是否有其他用户的许可需要接受（如果你切换了用户或使用了sudo）。

错误3: 下载超时或速度极慢这就是网络问题。除了配置镜像，可以尝试：

• 设置HTTP_PROXY和HTTPS_PROXY环境变量。
• 分段安装：先安装最小的platform-tools，再逐个安装其他大组件。
• 手动下载：从镜像站手动下载对应的zip包（如platform-tools-latest-linux.zip），解压到ANDROID_SDK_ROOT目录下对应位置。但这种方法需要你知道确切的文件命名规则和目录结构，不推荐新手使用。

错误4:bash: sdkmanager: command not found

• 确认~/.bashrc中的PATH设置正确。
• 确认执行了source ~/.bashrc。
• 尝试使用绝对路径执行：~/Android/Sdk/cmdline-tools/latest/bin/sdkmanager --list。如果这样可以，说明环境变量没配好。

5.3 为CI/CD环境优化：无头模式与缓存策略

在GitLab Runner、Jenkins或GitHub Actions等CI/CD环境中，我们通常需要在无图形界面的情况下静默安装。

关键点是使用--sdk_root参数明确指定SDK路径，并使用--verbose输出日志以便调试。一个典型的安装脚本如下：

#!/bin/bash export ANDROID_SDK_ROOT=/opt/android-sdk mkdir -p $ANDROID_SDK_ROOT # 下载并安装命令行工具（假设已下载到当前目录） unzip commandlinetools-linux-*.zip -d /tmp/ mkdir -p $ANDROID_SDK_ROOT/cmdline-tools/latest mv /tmp/cmdline-tools/* $ANDROID_SDK_ROOT/cmdline-tools/latest/ # 将sdkmanager加入PATH export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin # 接受许可 yes | sdkmanager —licenses —sdk_root=$ANDROID_SDK_ROOT # 静默安装必要组件（不显示进度条） sdkmanager —install “platform-tools” “platforms;android-34” “build-tools;34.0.0” —sdk_root=$ANDROID_SDK_ROOT —verbose

在CI/CD中，一定要将$ANDROID_SDK_ROOT目录作为缓存项。每次构建时，只需检查并更新SDK，而不是重新安装，这能极大缩短构建时间。

5.4 管理多个SDK版本

有时，不同的项目可能需要不同版本的构建工具或平台SDK。sdkmanager可以轻松管理多个版本。

• 列出特定类型的可用版本：虽然—list会列出所有，但你可以用grep过滤，如sdkmanager —list | grep “build-tools;”。
• 安装特定版本：直接指定版本号即可，如sdkmanager “build-tools;30.0.3” “platforms;android-30”。
• 卸载旧版本：使用—uninstall参数，例如sdkmanager —uninstall “build-tools;30.0.3”。

在你的项目build.gradle中，可以通过android.buildToolsVersion属性来指定使用哪个版本的构建工具。

6. 与构建工具（Gradle）的集成验证

安装配置好SDK后，最终目的是为了能成功编译项目。我们用一个简单的测试来验证整个环境是否工作正常。

6.1 创建或获取一个测试项目

你可以创建一个全新的Android项目，或者直接克隆一个简单的开源项目。这里，我们直接在本地创建一个最小的build.gradle文件来测试Gradle能否正确找到SDK。

在你的工作目录，创建一个test-build.gradle文件：

// test-build.gradle println “Android SDK Root: “ + System.getenv(‘ANDROID_SDK_ROOT’) println “Android Home: “ + System.getenv(‘ANDROID_HOME’) // 尝试定位android插件（这里只是测试类路径，不真正应用插件） try { def androidPlugin = org.gradle.api.internal.classpath.ModuleRegistry.class println “Gradle environment seems OK.” } catch (Exception e) { println “Gradle classpath issue: “ + e.message }

然后运行Gradle命令执行这个脚本：

cd /path/to/your/test/directory gradle -b test-build.gradle tasks

观察输出中是否打印出了正确的ANDROID_SDK_ROOT路径。这能验证Gradle运行时环境变量是否生效。

6.2 实际项目编译测试

更实际的测试是编译一个真实项目。如果你手头没有，可以用Android Studio创建一个新的“Empty Activity”项目，然后在命令行进入该项目根目录，尝试执行：

./gradlew clean assembleDebug —stacktrace

./gradlew是Gradle Wrapper，它会自动下载项目所需的Gradle版本。这个命令会清理项目，然后编译Debug版本的APK。

关键观察点：

1. 构建初期，Gradle是否会打印出类似Using SDK: /home/youruser/Android/Sdk的日志？
2. 构建过程中，是否在“Downloading”或“Unzipping” SDK组件？如果已经安装正确，这里应该很快跳过或直接使用本地缓存。
3. 构建最终是否成功，并在app/build/outputs/apk/debug/目录下生成.apk文件？

如果这一步成功，那么恭喜你，你的Linux Android SDK开发环境已经完全配置成功，可以投入到正式开发或自动化构建流程中了。

整个流程从系统准备到最终验证，虽然步骤不少，但每一步都有其必要性。尤其是在Linux服务器上，一个干净、正确、可复现的SDK环境，是保证团队开发效率和构建稳定性的基石。把这份配置文档化，甚至脚本化，能为未来的项目维护节省大量时间。