Mac独立Android命令行工具：从零配置到CI/CD实战指南

简介本资源是 Android 官方命令行工具集macOS 版专为无需完整 Android Studio 的开发者、CI/CD 工程师及自动化构建场景设计解决轻量级 SDK 管理、AVD 创建、APK 分析与代码检查等核心需求。压缩包共 101 个文件含 91 个核心 JAR 库支撑 lint、r8、proguard、kotlin 编译等、sdkmanager 与 avdmanager 主控工具、apkanalyzer 和 retrace 等实用命令行程序以及配套 README 和配置文件整体大小为 114.11MB。目前已有 214 人学习下载表明其在 DevOps 流程与 Headless 构建中具备实际落地价值。用户可直接解压即用快速初始化 Android SDK 环境执行依赖安装、模拟器管理、静态分析与混淆调试等任务尤其适合 Jenkins/GitLab CI 中集成 Android 构建流水线。1. 项目概述为什么你需要独立的 Android 命令行工具如果你在 Mac 上做 Android 开发大概率是从 Android Studio 开始的。这个 IDE 确实强大集成了 SDK 管理、模拟器、代码编辑和构建工具开箱即用。但时间一长你可能会遇到一些“别扭”的场景比如你只想在 CI/CD 流水线如 Jenkins、GitHub Actions里编译一个 APK难道要在服务器上也装一个几 GB 的 Android Studio或者你习惯用 Vim 或 VS Code 写代码只想用命令行来管理 SDK、编译项目不想启动那个“全家桶”。又或者你的项目构建脚本比如 Gradle在某个环节卡住了报错指向某个 SDK 工具版本不对你需要快速、精准地切换或安装特定版本的命令行工具而不是通过 IDE 的图形界面一层层点进去。这时一个独立的、轻量级的 Android 命令行工具包Command Line Tools就显得至关重要。它剥离了 IDE 的 GUI 外壳只保留最核心的 SDK 管理、平台工具和构建工具让你能通过终端Terminal完全掌控 Android 开发环境。我手头这个commandlinetools-mac-8092744_latest.zip就是 Google 官方为 Mac 系统提供的独立命令行工具包的最新版本版本号 8092744。它就像一个瑞士军刀虽然不如 Android Studio 功能全面但在自动化、脚本化和服务器端部署场景下是不可或缺的利器。2. 核心组件拆解压缩包里到底有什么下载并解压commandlinetools-mac-8092744_latest.zip后你得到的不是一个可以直接运行的.app应用而是一个结构清晰的目录树。理解这个结构是正确使用它的第一步。通常解压后会得到一个cmdline-tools目录其内部结构如下cmdline-tools/ └── latest/ ├── bin/ │ ├── sdkmanager │ ├── avdmanager │ └── ... ├── lib/ ├── NOTICE.txt └── source.properties2.1 核心可执行文件 (bin/目录)这是工具包的灵魂所在包含了几个关键的脚本和可执行文件sdkmanager: 这是最重要的工具没有之一。它是一个纯粹的包管理器用于列出、安装、更新和卸载 Android SDK 的各种组件。你可以通过它获取 Android 平台版本如platforms;android-33、系统镜像如system-images;android-33;google_apis;x86_64、构建工具如build-tools;33.0.0、平台工具如platform-tools包含adb,fastboot、模拟器、NDK 等。所有操作都通过命令行参数完成完美适配自动化脚本。avdmanager: 全称 Android Virtual Device Manager用于创建、删除和管理 AVDAndroid 虚拟设备。虽然sdkmanager可以下载系统镜像但将镜像组合成一台可启动的虚拟手机是avdmanager的职责。在无头headless服务器上创建用于自动化测试的 AVD 就靠它。其他工具: 可能还包括apkanalyzer用于分析 APK 文件构成、lint代码静态分析工具等它们同样是构建和优化流程中的重要环节。2.2 库文件与元数据 (lib/,NOTICE.txt,source.properties)lib/目录包含了上述命令行工具运行所依赖的 Java 库.jar文件。NOTICE.txt是版权和许可声明。source.properties是这个工具包自身的元数据文件里面记录了版本号如Pkg.Revision8092744、版本代码等关键信息。当你遇到工具本身的问题时查看这个文件能快速确认版本。这里有一个关键点Google 推荐的文件系统布局是将这个解压后的cmdline-tools目录放置在一个你自定义的 Android SDK 根目录下并且目录名必须就是cmdline-tools。例如假设你设定的 SDK 根目录是~/Library/Android/sdk那么完整的路径应该是~/Library/Android/sdk/cmdline-tools/latest/。这样设计是为了让sdkmanager能正确识别其工作环境并将后续下载的所有其他组件平台、构建工具等都存放在这个 SDK 根目录下的相应子文件夹里。3. 从零开始在 Mac 上的完整安装与配置流程理论清楚了我们开始实战。假设你拿到的是一个纯净的 Mac 系统或者你想彻底清理旧环境重新配置。以下是我多次搭建环境总结出的标准化流程我会解释每一步的意图而不仅仅是给命令。3.1 前置条件确保 Java 环境就绪Android 命令行工具本身是 Java 程序构建系统 Gradle 也是。因此一个正确配置的 Java 开发工具包JDK是必须的。虽然 macOS 可能自带 Java但版本可能不匹配。检查现有 Java打开终端输入java -version。如果显示版本号如openjdk version 17.0.8且版本在 11 以上目前 Android 开发推荐 JDK 17可以跳过安装。如果提示未安装或版本过低继续下一步。安装 JDK我强烈建议使用Homebrew来管理开发环境它比手动下载.pkg安装包更干净、易管理。如果你还没有 Homebrew先安装它访问 brew.sh 获取安装命令。安装 OpenJDK 17brew install openjdk17安装后brew 会提示你需要将 JDK 添加到PATH。通常会建议你执行类似echo export PATH/opt/homebrew/opt/openjdk17/bin:$PATH ~/.zshrc的命令如果你使用 Zsh这是 macOS Catalina 及之后的默认 shell。请务必执行它。让配置生效source ~/.zshrc。再次验证java -version应显示 OpenJDK 17 的相关信息。注意为什么是 JDK 17 而不是 8Google 官方 Android 工具链包括 AGP - Android Gradle Plugin已经全面转向对 JDK 11 的支持JDK 8 可能会在未来的构建中遇到兼容性问题。使用较新的 JDK 版本能避免潜在的构建失败。3.2 下载与解压命令行工具包你可以从 Android 开发者官网的“命令行工具”页面找到下载链接或者直接使用你已有的commandlinetools-mac-8092744_latest.zip文件。假设下载后的 ZIP 文件在~/Downloads目录。打开终端我们创建一个统一的 Android SDK 目录并按照 Google 推荐的结构放置工具包。# 创建 Android SDK 的根目录你可以选择其他位置如 ~/Android/Sdk mkdir -p ~/Library/Android/sdk # 解压命令行工具包到 SDK 根目录下并确保目录名为 cmdline-tools unzip ~/Downloads/commandlinetools-mac-8092744_latest.zip -d ~/Library/Android/sdk/ # 检查解压后的结构确认存在 latest 目录 ls -la ~/Library/Android/sdk/cmdline-tools/解压后你应该能看到~/Library/Android/sdk/cmdline-tools/latest/这个路径。3.3 配置环境变量这是让系统在任何终端会话中都能找到sdkmanager、adb等工具的关键步骤。我们需要修改 shell 的配置文件。打开你的 shell 配置文件。对于 macOS 默认的 Zsh是~/.zshrc。如果你使用 Bash则是~/.bash_profile。nano ~/.zshrc在文件末尾添加以下行# 设置 Android SDK 根目录 export ANDROID_HOME$HOME/Library/Android/sdk export ANDROID_SDK_ROOT$ANDROID_HOME # 有些工具认这个变量 # 将平台工具、构建工具和命令行工具添加到 PATH export PATH$PATH:$ANDROID_HOME/platform-tools export PATH$PATH:$ANDROID_HOME/build-tools # 这里会添加一个目录具体版本路径稍后会由 sdkmanager 创建 export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/binANDROID_HOME是一个历史悠久的变量很多脚本和工具包括旧版 Android Studio都依赖它。ANDROID_SDK_ROOT是另一个常用的变量设置它以兼容更多工具。将platform-tools和cmdline-tools/latest/bin加入PATH是必须的这样你才能直接运行adb,fastboot,sdkmanager。将build-tools目录加入PATH是为了让构建系统能找到aapt,zipalign等工具。注意build-tools下会有多个版本子目录如33.0.0将其父目录加入 PATH 后系统会自动搜索其下的子目录。保存并退出编辑器在 nano 中是CtrlX然后按Y再按回车。使配置立即生效source ~/.zshrc。3.4 首次运行 sdkmanager 并安装必要组件现在你的终端应该能识别sdkmanager命令了。但在使用前它需要先同意许可协议。列出所有可用的软件包sdkmanager --list。这个命令会输出一个非常长的列表包含平台、工具、附加组件、系统镜像等。第一次运行可能会提示你更新自身按提示操作即可。接受许可协议在安装任何组件前你必须接受 Android SDK 的许可协议。可以通过以下命令一次性接受所有未决的许可yes | sdkmanager --licenses这个命令会对你看到的所有许可提示自动回答 “y”。如果你希望手动查看可以不加yes |即sdkmanager --licenses然后对每个协议输入y并回车。安装核心组件对于最基本的 Android 开发环境你需要安装以下几样东西。我建议一次性安装用空格分隔包名sdkmanager platform-tools platforms;android-34 build-tools;34.0.0platform-tools: 包含adb(调试桥)、fastboot(刷机工具) 等核心工具。platforms;android-34: 安装 Android 14 (API 34) 的平台库和资源。你应该安装你的应用目标 API 级别对应的平台。查看项目的build.gradle文件中的compileSdk和targetSdkVersion。build-tools;34.0.0: 安装对应版本的构建工具。版本号通常与你的compileSdk匹配或略高。你可以通过sdkmanager --list查看所有可用的构建工具版本。安装模拟器系统镜像可选如果你需要在命令行创建 AVD还需要下载一个系统镜像。sdkmanager system-images;android-34;google_apis;x86_64这里安装的是适用于 x86_64 架构 CPU 的 Google API 镜像它包含了 Google 移动服务适合大多数应用测试。安装过程会显示进度条。所有组件都将被下载并安装到ANDROID_HOME目录下对应的子文件夹中。完成后你的~/Library/Android/sdk目录结构会变得丰富起来。4. 实战应用用纯命令行管理项目与设备环境配好了我们来点真格的。看看如何脱离 Android Studio完成日常开发中的关键任务。4.1 创建和管理 Android 虚拟设备 (AVD)在 CI 服务器上跑自动化测试或者在本地快速启动一个特定配置的模拟器命令行是唯一选择。列出所有可用的系统镜像在安装镜像后可以用avdmanager list查看。但更直接的是用sdkmanager --list看已安装的镜像。创建一个新的 AVD假设我们要创建一个名为test_avd_api34的设备使用我们刚才下载的镜像。avdmanager create avd -n test_avd_api34 -k system-images;android-34;google_apis;x86_64 -d pixel_5-n: 指定 AVD 的名称。-k: 指定系统镜像的标识符必须与sdkmanager --list中Installed packages:下的条目完全一致。-d: 指定设备定义。pixel_5是 Google 预定义的一个设备配置文件。你可以通过avdmanager list device查看所有可用的设备 ID。 命令执行中会询问你是否要创建自定义硬件配置文件通常直接回车选择默认no即可。启动这个 AVD虽然avdmanager能创建但启动模拟器需要另一个工具emulator它位于$ANDROID_HOME/emulator/目录下。确保这个目录也在你的 PATH 里可以像之前添加platform-tools一样将$ANDROID_HOME/emulator加入 PATH。# 无图形界面启动适用于服务器测试 emulator -avd test_avd_api34 -no-window -no-audio # 有图形界面启动本地开发 emulator -avd test_avd_api34 符号让命令在后台运行这样你就能继续使用当前终端窗口。管理 AVD删除 AVD 使用avdmanager delete avd -n test_avd_api34。4.2 构建一个 Android 项目假设你有一个现成的 Android 项目或者用命令行创建了一个新项目。创建一个新项目可选虽然不常用但你可以用gradle init来初始化一个项目不过对于标准的 Android 项目使用 Android Studio 的模板或从 GitHub 克隆现有项目更简单。进入项目根目录cd /path/to/your/android/project执行构建项目根目录下通常有一个gradlewGradle Wrapper脚本。使用它来构建可以确保使用项目指定的 Gradle 版本避免环境问题。# 清理构建产物 ./gradlew clean # 编译 Debug 版本的 APK ./gradlew assembleDebug # 编译 Release 版本的 APK需要配置签名 # ./gradlew assembleRelease # 运行所有单元测试 ./gradlew test # 在连接的设备或模拟器上安装并运行 Debug 版应用 ./gradlew installDebug构建输出的 APK 文件通常位于app/build/outputs/apk/debug/目录下。4.3 使用 adb 管理真实设备adb是连接手机和电脑的桥梁命令行下极其强大。连接设备用 USB 线连接 Android 手机并开启手机的“开发者选项”和“USB 调试”。查看已连接设备adb devices。列表中会显示设备的序列号。安装 APKadb install -r app-debug.apk。-r参数代表替换现有安装。查看日志adb logcat。这是排查崩溃和问题的利器。可以使用过滤器如adb logcat *:E只看错误日志或者adb logcat | grep MyAppTag只看特定标签的日志。拉取/推送文件# 从设备拉取文件到电脑 adb pull /sdcard/DCIM/Camera/photo.jpg ~/Desktop/ # 从电脑推送文件到设备 adb push ~/Documents/config.txt /sdcard/执行 Shell 命令adb shell可以进入设备的命令行环境。adb shell pm list packages可以列出所有已安装的应用包名。5. 进阶技巧与疑难排坑掌握了基础操作下面分享一些能提升效率、解决常见问题的进阶技巧。5.1 配置镜像源以加速下载sdkmanager默认从 Google 服务器下载组件在国内速度可能很慢甚至无法连接。我们可以配置国内镜像源。找到sdkmanager的配置文件。它通常位于$ANDROID_HOME/cmdline-tools/latest/bin/目录下但配置是用户级的。更可靠的方法是设置环境变量。在~/.zshrc中添加以下行# 设置 Android SDK 使用清华大学镜像源 export SDKMANAGER_OPTS-Djava.net.preferIPv6Addressesfalse -Dhttps.proxyHostmirrors.tuna.tsinghua.edu.cn -Dhttps.proxyPort443实际上更通用的方法是修改sdkmanager本身的更新站点。但通过环境变量设置代理是一种快速尝试的方法。更彻底的方案是修改$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager这个脚本文件找到调用 Java 的那一行在-Djava.util.logging.manager...后面添加镜像源参数但这涉及修改官方脚本不推荐。实际上对于sdkmanager最有效的方法是在执行命令时指定镜像源sdkmanager --verbose --sdk_root$ANDROID_HOME --channel0 --include_obsolete --proxyhttp --proxy_hostmirrors.tuna.tsinghua.edu.cn --proxy_port443 platform-tools但这个方法比较繁琐。目前最主流且稳定的方案是修改 Android SDK 的仓库源配置文件。推荐方案修改 repositories.cfg。关闭所有 Android Studio 和sdkmanager进程。找到文件~/.android/repositories.cfg如果不存在就创建。在其内容中或直接替换为### User Sources for Android SDK Manager count0这个文件的作用是禁用默认的 Google 源。然后我们需要在$ANDROID_HOME下创建一个repositories.cfg文件可能与上面的文件相同具体机制随版本变化最保险是两个地方都尝试。但更关键的一步是手动创建一个镜像站点的 XML 配置文件。在$ANDROID_HOME目录下创建或修改androidtool.cfg文件有时也有效或者更直接地设置 HTTP 代理环境变量让所有 Java 网络请求走代理这通常是最有效的export HTTP_PROXYhttp://your-proxy-host:port # 替换为你的可用代理地址 export HTTPS_PROXYhttp://your-proxy-host:port之后再用sdkmanager下载速度就会有显著改善。5.2 处理 “command not found: sdkmanager” 或 “无法运行 Java” 错误症状在终端输入sdkmanager后提示命令未找到。排查检查环境变量echo $PATH查看输出中是否包含.../cmdline-tools/latest/bin的路径。如果没有说明~/.zshrc修改未生效请检查拼写并执行source ~/.zshrc。检查路径是否存在ls -la ~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager。确保文件存在且有可执行权限chmod x可以添加。如果路径正确但仍报错可能是脚本的 shebang 行有问题。用head -n 1 $(which sdkmanager)查看第一行确保它指向正确的 Java 路径。症状运行sdkmanager时报错提示找不到或无法加载 Java 运行时。排查确认 Java 已安装且版本合适java -version。如果安装了多个 Java 版本可能需要显式设置JAVA_HOME。在~/.zshrc中添加export JAVA_HOME$(/usr/libexec/java_home -v 17) # 指定版本为 17 export PATH$JAVA_HOME/bin:$PATH然后source ~/.zshrc。/usr/libexec/java_home是 macOS 提供的工具可以帮你找到指定版本的 JDK 安装路径。5.3 管理多个 SDK 版本和构建工具版本大型项目或维护多个老项目时可能需要同时安装多个版本的平台或构建工具。安装多个版本直接用sdkmanager安装即可它们会并存于platforms/android-XX和build-tools/XX.Y.Z目录下。sdkmanager platforms;android-33 platforms;android-34 build-tools;33.0.2 build-tools;34.0.0项目指定版本在你的项目的app/build.gradle文件中通过compileSdk,targetSdkVersion和buildToolsVersion来指定使用哪个版本。Gradle 和构建系统会自动在$ANDROID_HOME下寻找对应的版本。android { compileSdk 34 buildToolsVersion 34.0.0 defaultConfig { targetSdk 34 } }切换默认版本谨慎通常不需要手动切换因为项目配置会决定。但如果你在命令行直接调用aapt等工具PATH 会指向build-tools目录系统会使用按字母顺序找到的第一个版本通常是版本号最高的。如果你想强制使用某个版本可以在命令中指定完整路径如$ANDROID_HOME/build-tools/33.0.2/aapt。5.4 在 CI/CD 中集成以 GitHub Actions 为例这是命令行工具最大的用武之地。以下是一个简化的 GitHub Actions 工作流片段展示如何设置 Android 环境并构建项目name: Android CI on: [push] jobs: build: runs-on: macos-latest # 使用 macOS 运行器 steps: - uses: actions/checkoutv3 - name: Set up JDK 17 uses: actions/setup-javav3 with: java-version: 17 distribution: temurin - name: Setup Android SDK uses: android-actions/setup-androidv3 - name: Accept Android SDK Licenses run: | yes | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --licenses - name: Install Android Platform and Build Tools run: | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager platform-tools platforms;android-34 build-tools;34.0.0 - name: Build with Gradle run: | chmod x ./gradlew ./gradlew assembleDebug在这个流程中我们使用了社区 Actionandroid-actions/setup-android来快速设置ANDROID_SDK_ROOT环境变量并下载命令行工具包然后直接用sdkmanager安装所需组件最后用gradlew构建。整个过程完全自动化无需图形界面。6. 维护与清理让开发环境保持清爽长期使用后SDK 目录可能会变得很大因为下载了多个版本的平台、系统镜像和构建工具。查看已安装的组件sdkmanager --list的输出中Installed packages:部分下列出的就是已安装的。留意那些Obsolete标记的它们可能已经不再需要。卸载不需要的组件使用sdkmanager --uninstall命令。例如要卸载旧的构建工具sdkmanager --uninstall build-tools;30.0.3。卸载前请确认没有项目依赖它。清理缓存SDK 组件下载的临时文件位于$ANDROID_HOME/.download和$ANDROID_HOME/.temp等目录可以安全删除。~/.gradle/caches/目录也可以定期清理以释放空间但下次构建时会重新下载依赖影响速度。更新命令行工具本身sdkmanager可以更新自己。运行sdkmanager --update。如果提示需要更新它会自动下载新版本的cmdline-tools包。更新后记得检查source.properties文件确认新版本号。将 Android 命令行工具作为你 Mac 上独立于 Android Studio 的开发基石能极大地提升你对构建流程的理解和控制力。从自动化脚本到持续集成从快速排查到环境隔离这套工具链的价值会在你深入 Android 开发生态的过程中不断显现。刚开始接触时可能会觉得繁琐但一旦熟练你会发现这种“一切尽在掌握”的感觉远比依赖一个黑盒式的 IDE 要踏实得多。本文还有配套的精品资源点击获取