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 libstdc6 -y2.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-toolsANDROID_SDK_ROOT: 明确指向SDK的根目录这是现在推荐的方式ANDROID_HOME已逐渐被弃用。PATH: 添加了两个路径。第一个是sdkmanager的路径第二个是platform-tools的路径里面包含adb和fastboot这个目录稍后我们会用sdkmanager安装。保存并退出编辑器在nano中是CtrlX然后按Y确认再按Enter。让配置立即生效source ~/.bashrc现在验证sdkmanager是否可以运行sdkmanager --version如果输出类似10.0这样的版本号恭喜你命令行工具安装成功了。如果提示“命令未找到”请检查路径是否正确特别是latest目录层级。是否执行了source ~/.bashrc。是否在同一个终端会话中。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编译环境以下几个组件是必须的平台工具platform-tools: 包含adb调试桥、fastboot等基础工具。构建工具build-tools: 包含将源代码编译成APK的工具如aapt、dx现已被D8/R8取代、zipalign等。你需要选择与你的项目Gradle配置匹配的版本。平台SDKplatforms: 对应特定Android API级别的SDK包含框架库、系统资源等。你需要安装你应用所targetSdkVersion指定的平台。命令行工具更新cmdline-tools: 是的命令行工具本身也可以通过sdkmanager更新到其他版本。假设我们要安装当前常用的版本命令如下sdkmanager “platform-tools” “platforms;android-34” “build-tools;34.0.0”命令格式解析组件名称需要用引号括起来特别是包含分号;的时候。platforms;android-34表示安装Android API 34Android 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 —proxyhttp —proxy_hostmirrors.tuna.tsinghua.edu.cn —proxy_port80但是请注意较新版本的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。关键观察点构建初期Gradle是否会打印出类似Using SDK: /home/youruser/Android/Sdk的日志构建过程中是否在“Downloading”或“Unzipping” SDK组件如果已经安装正确这里应该很快跳过或直接使用本地缓存。构建最终是否成功并在app/build/outputs/apk/debug/目录下生成.apk文件如果这一步成功那么恭喜你你的Linux Android SDK开发环境已经完全配置成功可以投入到正式开发或自动化构建流程中了。整个流程从系统准备到最终验证虽然步骤不少但每一步都有其必要性。尤其是在Linux服务器上一个干净、正确、可复现的SDK环境是保证团队开发效率和构建稳定性的基石。把这份配置文档化甚至脚本化能为未来的项目维护节省大量时间。