简介面向无需安装完整 Android Studio 的 macOS 开发者这份 Android 命令行工具包提供 SDK 管理、模拟器创建、APK 分析、Lint 静态检查等核心能力适合在轻量级环境下构建、调试与维护 Android 项目。压缩包共 104 个文件总量 146.49MB其中以 93 个 jar 依赖为主涵盖 Kotlin 编译器、R8 混淆、Protobuf 及 Guava 等运行库附带的 sdkmanager、avdmanager、apkanalyzer、lint、retrace 等命令行脚本分别用于 SDK 组件安装、虚拟设备管理、APK 深度解析、代码检查与崩溃栈反混淆。目前已有 199 人学习下载。通过该工具集读者可脱离 Android Studio 独立完成 SDK 组件更新、构建环境配置及问题诊断后续自行组合 Gradle 等构建链时也能灵活补齐所需依赖对偏好命令行操作或云端/服务器构建场景的开发者尤具实用价值。1. 为什么 macOS 上要单独装 Android 命令行工具包拿到commandlinetools-mac-11076708-latest.zip这个文件意味着你已经决定不完全依赖 Android Studio 的图形界面来管理 SDK。这个 zip 是 Android 命令行工具的核心分发形态里面装着 sdkmanager、avdmanager、apkanalyzer 等脚本后续安装 platform-tools、platforms、build-tools、模拟器镜像全部通过 sdkmanager 这一个入口完成。文件名的11076708是工具包自身的 build number不是 Android 版本号latest也只是下载站在文件名上的泛称真正版本要看解压后的 source.properties。CI 机上没有显示器、mac 上同时维护多套 JDK、或者你只想用 adb 处理真机时这套命令行工具都比启动 Android Studio 更快、更容易脚本化。2. 在 mac 上安装 commandlinetools 的最小步骤与环境变量2.1 解压到正确目录将 zip 内容套进 cmdline-tools/latest拿到 zip 后不要双击解压先规划 SDK 根目录。macOS 上通常约定~/Library/Android/sdk这是 Android Studio 默认搜索路径也是platform-tools、platforms、build-tools等所有组件的落脚点。命令行工具包解压后只有一个顶层目录cmdline-tools里面是bin/、lib/、source.properties。你需要把它整体放到cmdline-tools/latest最终路径必须是.../cmdline-tools/latest/bin/sdkmanager。SDK_ROOT$HOME/Library/Android/sdk mkdir -p $SDK_ROOT/cmdline-tools unzip ~/Downloads/commandlinetools-mac-11076708-latest.zip -d /tmp/cmdline-tools-installer # 解压后顶层目录是 /tmp/cmdline-tools-installer/cmdline-tools mv /tmp/cmdline-tools-installer/cmdline-tools $SDK_ROOT/cmdline-tools/latest rm -rf /tmp/cmdline-tools-installer这里把 zip 解压到临时目录再用mv把整个cmdline-tools文件夹放成latest可以避免 macOS 归档工具自动创建多余路径也不会污染已经存在的 SDK 目录。如果你直接在$SDK_ROOT里解压会得到$SDK_ROOT/cmdline-tools/bin/sdkmanager缺少latest这一层。sdkmanager 启动时会根据自身路径向上推导 SDK 根目录目录层级不对就会直接退出。latest是固定目录名换成版本号或日期虽然看着清楚但 Gradle 和 Android Studio 不会按你自定义的规则去扫描。2.2 配置 JAVA_HOME、ANDROID_HOME 与 PATH 环境变量sdkmanager 和 avdmanager 都是 Java 程序macOS 上必须先有 JDK。新版 commandlinetools 构建在 Java 17 上如果本机只有 Java 8运行时会直接报UnsupportedClassVersionError。可以用/usr/libexec/java_home -V查看已安装的 JDK如果装了 Android Studio直接复用它的 JBR 最省事路径是/Applications/Android Studio.app/Contents/jbr/Contents/Home。export ANDROID_HOME$HOME/Library/Android/sdk export ANDROID_SDK_ROOT$ANDROID_HOME export JAVA_HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulatorANDROID_HOME是 Android Studio、Gradle 与 sdkmanager 识别 SDK 根目录的主变量ANDROID_SDK_ROOT是旧版工具链仍会读取的别名两个都设置可以避免老脚本找不到路径PATH 里的三段分别对应sdkmanager/avdmanager入口、adb/fastboot和模拟器可执行文件。注意platform-tools和emulator目录在刚装完 commandlinetools 时并不存在要等第 3 章安装完对应组件后 adb 才会出现所以第一次运行adb version报 command not found 是正常现象。变量建议值用途ANDROID_HOME$HOME/Library/Android/sdkGradle、Studio、sdkmanager 定位 SDK 根目录ANDROID_SDK_ROOT$ANDROID_HOME兼容旧版工具链的必要别名JAVA_HOMEAndroid Studio JBR 或 JDK 17 路径sdkmanager、avdmanager 的 Java 运行时PATH追加 latest/bin、platform-tools、emulator命令行直接调用 sdkmanager、adb、emulator配置完成后执行source ~/.zshrc再运行sdkmanager --version。如果输出一行版本号例如11076708说明目录结构、JAVA_HOME、PATH 已经串起来了。此时不要急着装东西先用find $ANDROID_HOME -maxdepth 2 -type d看一眼目录层级确认没有把 cmdline-tools 直接铺到 SDK 根目录。2.3 常见的目录坑为什么解压了还是 command not found经常有人把解压出来的cmdline-tools放到$ANDROID_HOME/cmdline-tools/11076708这种带版本号的目录里然后发现 Gradle 或 Android Studio 识别不到。原因是工具链固定寻找cmdline-tools/latest不会扫描所有子目录。zip 文件名里虽然带了11076708但解压后你仍然要把目录放到latest下否则 sdkmanager 推导出的 SDK 根目录就不成立。如果你需要保留历史版本常见做法是先备份整个latest目录再覆盖而不是为每个 build number 单独建目录。备份后 SDK 根目录里有且只有一个latestAndroid Studio 的 SDK 管理器才不会出现组件无法勾选或状态异常。遇到sdkmanager: command not found第一反应不是改 PATH而是检查$ANDROID_HOME/cmdline-tools/latest/bin是否存在如果文件在再检查 JAVA_HOME 是否指向了可用的 JDK 17。3. 用 sdkmanager 安装 Android SDK 组件从 adb 到模拟器镜像3.1 package 命名规则与 sdkmanager 的常用参数sdkmanager 把 SDK 里每个可安装单元称为 package包名用分号分隔多级路径例如platforms;android-34。分号在 bash 里是命令分隔符所以包名必须用双引号包住否则会被 shell 拆开。最常用的参数是列表、安装、许可证和频道控制下面是一个最小操作组# 查看可安装与已安装包 sdkmanager --list # 只看已安装内容 sdkmanager --list_installed # 接受所有许可证后安装三件套 yes | sdkmanager --licenses /dev/null sdkmanager --install platform-tools platforms;android-34 build-tools;34.0.0--list的输出会同时列 installed packages 和 available packages内容很长我通常直接sdkmanager --list | grep platform过滤。--channel3能看到 dev/canary 版本默认只显示稳定版--channel0可以强制只看稳定版。--sdk_root...显式指定 SDK 根目录在ANDROID_HOME未设置时很有用。yes | sdkmanager --licenses /dev/null把交互式确认统一打成 y否则第一次安装会卡在许可证协议上CI 环境里直接超时。3.2 常用组件包名与最小安装组合下面这张表是 macOS 上最小构建环境常装的包实际包名版本以sdkmanager --list列出的为准package 名称作用典型包名platform-toolsadb、fastboot、mkbootimg 等设备侧工具platform-toolsplatforms对应 API level 的 android.jar 与公共资源platforms;android-34build-toolsaapt2、d8、apksigner 等编译链接工具build-tools;34.0.0emulator命令行模拟器本体emulatorsystem-images模拟器运行所需的系统镜像system-images;android-34;google_apis;arm64-v8a注意platform-tools与build-tools是两个不同包前者负责连接设备后者负责把代码变成 APK。只装platform-tools时可以直接用 adb 操作真机但 Gradle 构建仍会去找build-tools所以 CI 环境里三样最好一起装。装完后 SDK 根目录新增的目录和 package 名一一对应这些目录由 sdkmanager 自己创建不要手动往platforms目录里拷贝 android.jar那样sdkmanager --list_installed不会认可。3.3 先接受许可证再安装的完整命令序列一次性安装上表全部组件推荐写成四条命令export ANDROID_HOME$HOME/Library/Android/sdk # 接受所有协议 yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses /dev/null # 安装核心组件 $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install \ platform-tools \ platforms;android-34 \ build-tools;34.0.0 # 安装模拟器与系统镜像 $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install \ emulator \ system-images;android-34;google_apis;arm64-v8a第一条命令里的yes会不断输出 y管道给 sdkmanager 跳过交互式确认 /dev/null丢弃许可证全文第二条和第三条分两次安装便于单独确认模拟器镜像下载失败时不会把核心组件一起回滚。如果你在 Intel mac 上运行把arm64-v8a改成x86_64否则创建 AVD 时会报 ABI 不匹配。下载过程不显示单文件进度感觉像卡住其实是大镜像在传输看网络活动比盯终端更可靠。安装完成用sdkmanager --list_installed核对。如果某个包显示 installed 但目录找不到说明安装被中断把对应目录删掉再 install 一次即可。不要把 commandlinetools 安装的组件和 Android Studio 自动下载的组件混放在两个 SDK 根目录Gradle 的local.properties指向哪个根目录构建就使用哪套组件混放只会让版本号对不上。4. 在命令行里创建模拟器并用 adb 完成联调4.1 用 avdmanager 创建可用模拟器镜像AVD 是 Android Virtual Device 的缩写avdmanager 与 sdkmanager 在同一个 bin 目录下。创建 AVD 前必须先安装对应的 system-images 和 emulator。命令中的-d指定设备配置设备 id 用avdmanager list device查询不同版本工具内置的设备列表有差异直接写pixel_7在新版本可用旧版本未必有。echo no | avdmanager create avd \ -n ci34 \ -k system-images;android-34;google_apis;arm64-v8a \ -d pixel_7echo no回答“是否创建自定义硬件配置文件”的提问后续键盘、鼠标、内存等设置都可以直接改~/.android/avd/ci34.avd/config.ini所以这里选择 no。-k必须指定已安装的完整 system-image 包名与第 3 章安装的镜像保持一致如果 ABI 写错avdmanager 可能不报错但模拟器启动时会立即退出。创建完用avdmanager list avd验证正常会显示 AVD 的 Name 和 Path。如果需要限制 CI 机器内存在 config.ini 里追加hw.ramSize2048这比每次启动时传一堆参数更可控。4.2 启动无窗口模拟器并等待系统完全启动macOS 上直接启动带 UI 的模拟器会打开模拟器窗口CI 或远程机器上更常见的是无窗口模式并用 adb 等待系统就绪export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator emulator -avd ci34 -no-window -no-audio -gpu swiftshader_indirect adb wait-for-device until [ $(adb shell getprop sys.boot_completed 2/dev/null | tr -d \r) 1 ]; do sleep 2 done adb devices-no-window不创建图形窗口适合服务器环境-no-audio禁用音频后端避免没有声卡的机器报错-gpu swiftshader_indirect使用软件渲染防止 host GPU 驱动导致模拟器重启。adb wait-for-device只保证设备节点出现不代表系统启动结束所以后续用sys.boot_completed属性做轮询。tr -d \r去掉 adb shell 输出的回车符否则字符串比较永远不相等。启动参数组合很多常用配置可以做一张表快速查阅参数作用-avd指定要启动的 AVD 名称-no-window无窗口运行仅保留 adb 访问-no-audio不初始化音频设备-gpu swiftshader_indirect强制软件渲染-wipe-data清空 AVD 用户数据后重新启动4.3 从构建产物安装 APK 到命令行模拟器的完整脚本把组件安装、AVD 创建、启动、等待和安装 APK 串起来就是一个可复用的最小 CI 工作流#!/bin/bash set -euxo pipefail ANDROID_HOME$HOME/Library/Android/sdk SDKMANAGER$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator yes | $SDKMANAGER --licenses /dev/null $SDKMANAGER --install \ platform-tools \ platforms;android-34 \ build-tools;34.0.0 \ emulator \ system-images;android-34;google_apis;arm64-v8a echo no | $ANDROID_HOME/cmdline-tools/latest/bin/avdmanager create avd \ -n ci34 -k system-images;android-34;google_apis;arm64-v8a -d pixel_7 || true emulator -avd ci34 -no-window -no-audio -gpu swiftshader_indirect adb wait-for-device until [ $(adb shell getprop sys.boot_completed 2/dev/null | tr -d \r) 1 ]; do sleep 2 done adb install -r app-release.apk脚本开头set -euxo pipefail保证任一步失败立即退出避免后续命令在半坏环境上继续执行|| true是因为已有同名 AVD 时 create 会返回非零严格 CI 可以先avdmanager delete avd -n ci34再创建。adb install -r的-r表示覆盖安装适合反复跑测试不会因为版本号相同而失败。脚本不依赖 Android Studio只靠 commandlinetools 下载的组件就能完成无头联调这也是这个 zip 对 CI、远程构建机的核心价值。5. 验证安装与处理 Android Studio 里的 SDK 无法勾选问题5.1 快速验证工具链状态安装完成后不要急着打开 IDE先在终端把链路跑通sdkmanager --list_installed adb version avdmanager list avdsdkmanager --list_installed输出的包名和版本是排查 Gradle 构建失败时的第一依据。如果显示的 build-tools 版本和 Gradle 请求的版本不一致常见报错是SDK Build Tools revision X is too low用sdkmanager --install build-tools;X补上不用去 Android Studio 里乱点。5.2 从 source.properties 核对 commandlinetools 精确版本zip 文件名里的 latest 是下载站的别名真正锁定的 build 号记录在source.properties里grep Pkg.Revision $ANDROID_HOME/cmdline-tools/latest/source.properties输出形如Pkg.Revision11076708。排查问题时先看这个文件再对比项目要求避免目录名是 latest实际内容却是几天前被覆盖的旧版本。source.properties同时记录了Pkg.Desc帮你确认没有把 Windows 或 Linux 版本的压缩包下载到 mac 上。5.3 排查 Android Studio SDK 无法勾选回到 Android Studio 后发现 SDK Manager 里组件无法勾选多半是命令行工具包和 IDE 共用同一个ANDROID_HOME但 latest 目录缺失或权限不对。先在命令行确认~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager --version能正常输出若命令行正常、IDE 仍异常检查 Android Studio 的 SDK 位置设置确认它指向同一个ANDROID_HOME。不要同时让 Android Studio 和命令行工具都往 latest 目录写入两个版本交替覆盖会留下不可预期的半覆盖状态。清理方法是完全删除 latest 目录重新按第 2 章的步骤解压再运行一次sdkmanager --licenses接受协议最后用第 5.1 节的命令重建组件索引。最后把 zip 文件保留到本地固定位置记录实际使用的source.properties版本号下次在 CI 或另一台 mac 上重建环境时直接安装这个具体 build而不是重新下载一份最新的 latest 文件名。本文还有配套的精品资源点击获取