Mac 不装 Android Studio 搭建完整 Android SDK 命令行工具链指南

简介这份资源是面向 macOS 用户的 Android 命令行工具包commandlinetools-mac-8512546_latest.zip适合不想安装完整 Android Studio、却需要独立管理 SDK 与构建环境的开发者也适用于 CI 服务器、自动化脚本等轻量化场景。压缩包共 100 个文件约 108.88MB以 90 个 jar 库文件为核心并包含 sdkmanager、avdmanager、apkanalyzer、lint、retrace、screenshot2、profgen 等命令行可执行文件及配套说明文档覆盖 SDK 包管理、虚拟设备创建、APK 分析、代码检查与堆栈还原等常用能力。其中 sdkmanager 可用于下载和更新各类 SDK 组件avdmanager 负责模拟器镜像与设备管理apkanalyzer 与 lint 则帮助定位包体结构与代码问题。目前已有 250 人学习下载适合需要脱离图形界面、以脚本方式搭建 Android 开发或持续集成环境的中高级开发者参考使用。1. 从 commandlinetools-mac-8512546_latest.zip 说起Mac 上不装 Android Studio 也能搭出完整 SDK如果你在 Mac 上只想跑 Gradle 构建、写 CI 脚本或者单纯不想为了一个sdkmanager下载几个 G 的 Android Studio那commandlinetools-mac-8512546_latest.zip就是绕不开的起点。这个压缩包是 Google 官方提供的 macOS 版命令行工具集解压后核心就是cmdline-tools目录里面装着sdkmanager、avdmanager、adb、apkanalyzer等一整套命令行入口。它解决的不是“怎么开发 App”而是“怎么在没有图形界面的机器上把 Android SDK 装齐、把构建链路跑通”。适合谁适合做持续集成、做自动化打包、在远程 Mac 或容器里编译 Android 项目的工程师也适合想搞明白 Android Studio 背后到底调了哪些工具的人。8512546 这个版本号对应的是 cmdline-tools 的一个具体发布批次不同批次目录结构略有差异后面会讲怎么处理。2. 解压之后先别急着用目录布局与 sdkmanager 的第一次握手2.1 为什么不能直接双击解压到任意目录commandlinetools-mac-8512546_latest.zip解压出来是一个cmdline-tools文件夹里面是bin、lib等子目录。很多人直接把它丢到~/Downloads或者/Applications下面然后运行./bin/sdkmanager --list结果报错说找不到 SDK 根目录或者提示Warning: Could not create settings。原因在于sdkmanager会去推断 SDK 的安装根路径它默认认为自己的上级目录就是 SDK 根而cmdline-tools本身只是 SDK 的一个子组件。正确的做法是手动构造一个标准的 SDK 目录树把cmdline-tools放到latest子目录下这样sdkmanager才能正确识别。常见做法是# 假设你把 zip 解压到了 ~/Downloads mkdir -p ~/Library/Android/sdk/cmdline-tools mv ~/Downloads/cmdline-tools ~/Library/Android/sdk/cmdline-tools/latest这样~/Library/Android/sdk就是 SDK 根cmdline-tools/latest是工具集。注意latest这个目录名不是随便起的sdkmanager会优先识别cmdline-tools/latest/bin下的可执行文件如果你放成cmdline-tools/8512546某些脚本会找不到入口。2.2 配置环境变量ANDROID_HOME 与 PATH 的先后顺序目录摆好之后需要让终端知道 SDK 在哪。编辑~/.zshrcmacOS 默认 shell 现在是 zshexport ANDROID_HOME$HOME/Library/Android/sdk export ANDROID_SDK_ROOT$ANDROID_HOME export PATH$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH这里有两个变量ANDROID_HOME和ANDROID_SDK_ROOT。老版本工具认ANDROID_HOME新版本逐渐迁移到ANDROID_SDK_ROOT两个都设上最省心。PATH里把cmdline-tools/latest/bin放在前面是为了让sdkmanager和avdmanager优先被找到platform-tools是后面装adb的地方先预留。改完执行source ~/.zshrc然后验证sdkmanager --version如果输出了版本号比如 8.0 或 9.0 之类说明工具本身能跑了。如果报command not found检查PATH里路径有没有拼错或者latest/bin下有没有sdkmanager这个可执行文件。2.3 用 sdkmanager 装平台、构建工具和 platform-toolssdkmanager是整套工具的核心它负责从 Google 的仓库拉取 SDK 组件。先看有哪些包可用sdkmanager --list输出会分“Installed packages”和“Available Packages”两段。第一次跑的时候 Installed 是空的。接下来装最常用的三件套sdkmanager platform-tools platforms;android-34 build-tools;34.0.0参数说明platform-tools提供adb、fastboot等platforms;android-34是 Android 14 的编译平台Gradle 构建时compileSdk要跟它对应build-tools;34.0.0是构建工具链包含aapt2、d8、zipalign等。版本号可以根据你项目的build.gradle调整但建议 platform 和 build-tools 的大版本保持一致避免资源编译时出现玄学问题。装完之后再跑sdkmanager --listInstalled 段里应该能看到这三项。此时adb已经在platform-tools目录下adb version能输出版本号就说明链路通了。提示如果下载卡住或者超时可以试试sdkmanager --list --verbose看具体卡在哪个仓库地址。国内网络环境下有时候需要配置代理但这不是本文讨论范围遇到时优先检查网络连通性。3. 用命令行工具跑通一个最小 Android 构建从 Gradle 到 APK3.1 准备一个最小项目结构没有 Android Studio照样可以手写一个能构建的工程。最小结构如下MyApp/ build.gradle settings.gradle app/ build.gradle src/main/AndroidManifest.xml src/main/java/com/example/myapp/MainActivity.javasettings.gradle里写pluginManagement { repositories { google() mavenCentral() gradlePluginPortal() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } } rootProject.name MyApp include :app根目录build.gradleplugins { id com.android.application version 8.2.0 apply false }app/build.gradleplugins { id com.android.application } android { namespace com.example.myapp compileSdk 34 defaultConfig { applicationId com.example.myapp minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 } buildTypes { release { minifyEnabled false } } }AndroidManifest.xml里声明一个 ActivityMainActivity.java写一个最简单的Activity子类即可。这些文件用命令行创建完全没问题mkdir -p加cat重定向就能搞定。3.2 用 gradlew 触发构建观察 SDK 路径是否被正确识别项目里通常会有 Gradle Wrapper如果没有可以用系统 Gradle 生成gradle wrapper --gradle-version 8.2然后执行./gradlew assembleDebug这一步会触发 Android Gradle Plugin 去调用sdkmanager装过的那些组件。如果ANDROID_HOME没设对会报SDK location not found。如果build-tools版本不匹配会报Failed to find Build Tools revision。构建成功后APK 在app/build/outputs/apk/debug/app-debug.apk。参数说明assembleDebug是任务名对应 debug 变体如果想构建 release 且不签名用assembleRelease但需要配置签名或者至少一个空的 signingConfig。--stacktrace和--info是排错时常用的附加参数能看到 AGP 到底在调哪个 SDK 组件。3.3 用 apkanalyzer 和 adb 验证产物构建出来的 APK 可以用apkanalyzer检查apkanalyzer apk summary app/build/outputs/apk/debug/app-debug.apk会输出包名、版本号、文件大小等。apkanalyzer就在cmdline-tools/latest/bin下不需要额外安装。如果有模拟器或者真机连着adb install可以直接装adb install -r app/build/outputs/apk/debug/app-debug.apk-r表示替换已存在的应用。装完用adb shell am start -n com.example.myapp/.MainActivity启动。这一整套流程走通说明commandlinetools-mac-8512546_latest.zip提供的工具链已经能独立支撑 Android 构建不依赖 Android Studio 的图形界面。注意apkanalyzer在部分 cmdline-tools 版本里需要额外装cmdline-tools;latest组件如果提示找不到命令先跑sdkmanager cmdline-tools;latest再试。4. 避坑与排查命令行工具在 Mac 上的五个血泪翻车点4.1 现象sdkmanager 报 “Could not determine SDK root”原因cmdline-tools没有放在sdk-root/cmdline-tools/latest这个标准路径下或者latest目录名被改成了版本号。sdkmanager会从自己的位置向上找两级如果找不到platform-tools或platforms目录就认为 SDK 根不合法。解决严格按照~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager这个层级摆放。如果已经放错用mv调整不要用软链接糊弄某些脚本会解析真实路径。4.2 现象Gradle 构建时报 “Failed to install the following Android SDK packages”原因项目build.gradle里声明的compileSdk或buildToolsVersion在本地没有安装。AGP 会尝试自动下载但如果没有接受 license下载会中断。解决先手动装齐sdkmanager platforms;android-34 build-tools;34.0.0 yes | sdkmanager --licensesyes |是自动接受所有 licenseCI 环境里常用。本地跑一次之后license 文件会写到~/Library/Android/sdk/licenses后续构建就不会再卡。4.3 现象adb 能识别设备但 install 时报 “INSTALL_FAILED_INSUFFICIENT_STORAGE”原因模拟器或真机存储空间不足或者 APK 本身太大。跟 cmdline-tools 没关系但排查时容易误以为是 SDK 问题。解决adb shell df看剩余空间清理无用应用或换一个存储更大的设备。如果是模拟器可以在 AVD 配置里增大disk.dataPartition.size。4.4 现象sdkmanager 下载到一半卡死重试后报 “File not found” 或 “Checksum mismatch”原因网络中断导致临时文件损坏sdkmanager的缓存目录里留下了半截文件。解决删掉缓存重来。缓存通常在~/.android/cache或者 SDK 目录下的.temp文件夹。直接rm -rf ~/.android/cache再跑一次sdkmanager它会重新下载。如果反复失败检查磁盘剩余空间sdkmanager解压时需要额外空间。4.5 现象在 Apple Silicon Mac 上跑 cmdline-tools 报 “Bad CPU type in executable”原因下载的是 x86_64 版本的 cmdline-tools而机器是 arm64。8512546 这个批次可能有不同架构的包如果拿错了就会报这个。解决确认下载的是 macOS 通用版或者 arm64 版。如果已经装了 x86 版可以通过 Rosetta 运行但更干净的做法是换用对应架构的 zip。file $(which sdkmanager)可以看可执行文件的架构。5. 进阶把命令行工具塞进 CI 与多版本 SDK 共存5.1 在 GitHub Actions 的 macOS runner 上复现这套环境CI 里没有图形界面正好是 cmdline-tools 的主场。一个典型的步骤片段# 下载并解压 cmdline-tools curl -o cmdline-tools.zip https://dl.google.com/android/repository/commandlinetools-mac-8512546_latest.zip mkdir -p $HOME/Library/Android/sdk/cmdline-tools unzip -q cmdline-tools.zip -d $HOME/Library/Android/sdk/cmdline-tools mv $HOME/Library/Android/sdk/cmdline-tools/cmdline-tools $HOME/Library/Android/sdk/cmdline-tools/latest # 环境变量 export ANDROID_HOME$HOME/Library/Android/sdk export PATH$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH # 接受 license 并安装组件 yes | sdkmanager --licenses sdkmanager platform-tools platforms;android-34 build-tools;34.0.0 # 构建 ./gradlew assembleDebug这段脚本的关键在于unzip之后多了一层cmdline-tools目录需要mv成latest。CI 缓存可以把$HOME/Library/Android/sdk整个缓存起来下次直接跳过下载。5.2 多版本 SDK 共存时怎么切换一个项目用 android-33另一个用 android-34不需要来回卸载。sdkmanager支持同时安装多个 platform 和 build-toolsGradle 会根据compileSdk自动选对应的版本。只要ANDROID_HOME指向同一个 SDK 根所有版本都在platforms/和build-tools/下并存。如果某个项目需要特定版本的 cmdline-tools可以把不同批次解压到cmdline-tools/8512546和cmdline-tools/latest然后在脚本里临时改PATH指向对应目录。但注意sdkmanager本身会写~/.android下的配置多版本混用时尽量保持latest为当前主用版本。5.3 一个验证 SDK 完整性的小技巧在投入 CI 之前我习惯用一条命令检查关键组件是否齐全for cmd in sdkmanager avdmanager adb apkanalyzer; do command -v $cmd /dev/null 21 echo $cmd OK || echo $cmd MISSING done如果apkanalyzer显示 MISSING说明cmdline-tools;latest组件没装全跑sdkmanager cmdline-tools;latest补上。这个检查花不了几秒但能避免构建到一半才发现工具缺失。我自己在 Mac 上折腾这套东西最大的教训是不要用sudo去装 SDK也不要把 SDK 放到/usr/local下面。权限问题一旦出现后面每个命令都要加sudoGradle 构建时又会因为权限不一致报一堆莫名其妙的错。老老实实放在用户目录下~/Library/Android/sdk就是最省心的位置。希望帮到你。本文还有配套的精品资源点击获取