簡(jiǎn)介本資源是官方 Android 命令行工具最新版macOS 平臺(tái)專(zhuān)為輕量級(jí) Android 開(kāi)發(fā)者、CI/CD 工程師及命令行偏好者設(shè)計(jì)適用于無(wú)需完整 Android Studio 的場(chǎng)景可獨(dú)立完成 SDK 管理、模擬器控制、APK 分析與構(gòu)建診斷等核心任務(wù)。壓縮包共 101 個(gè)文件含 91 個(gè)核心功能 JAR 包如 r8.jar、lint-checks.jar、guava-30.1-jre.jar 等、sdkmanager 與 avdmanager 主控腳本、apkanalyzer 和 lint 等實(shí)用二進(jìn)制工具以及配置文件與說(shuō)明文檔整體體積 114.11MB結(jié)構(gòu)精簡(jiǎn)、開(kāi)箱即用。目前已有 214 人學(xué)習(xí)下載適合希望快速搭建無(wú) IDE 構(gòu)建環(huán)境、集成自動(dòng)化流水線或深入理解 Android 構(gòu)建底層機(jī)制的中高級(jí)開(kāi)發(fā)者。 這個(gè)壓縮包名字你可能有點(diǎn)眼生但只要是做Android開(kāi)發(fā)、又不喜歡被Android Studio綁架的人一定繞不開(kāi)它。commandlinetools是Google官方發(fā)布的Android SDK命令行工具包mac版本就是標(biāo)題里這個(gè)commandlinetools-mac-8092744_latest.zip。它解決的核心問(wèn)題是在不安裝完整IDE的情況下用純命令行完成SDK組件的下載、安裝、更新、管理以及模擬器AVD的創(chuàng)建與啟動(dòng)。適合用腳本搭建CI構(gòu)建環(huán)境、用命令行管理多套SDK、或者純粹喜歡輕量開(kāi)發(fā)環(huán)境的人。1. Android命令行工具的設(shè)計(jì)思路與適用場(chǎng)景1.1 為什么Google要單獨(dú)拆出命令行工具包早些年Android SDK是一個(gè)完整的大壓縮包里面既包含IDE、SDK Manager界面、又有底層工具體積大、更新繁瑣。后來(lái)Google把Android Studio和底層SDK徹底分離面向普通開(kāi)發(fā)者的圖形化SDK Manager被集成進(jìn)IDE而純粹的SDK管理能力則被剝離成獨(dú)立的commandlinetools。這個(gè)調(diào)整讓兩類(lèi)人群都受益用Android Studio的人不需要在IDE之外再維護(hù)一套重復(fù)的工具而命令行用戶則可以只拿一個(gè)幾十MB的zip包配上JDK就能完全掌控SDK生命周期。commandlinetools這個(gè)包的核心價(jià)值在于它把sdkmanager、avdmanager、apkanalyzer、retrace等一票實(shí)用工具統(tǒng)一打包替代了早期SDK Manager圖形界面能做的所有事。尤其是sdkmanager它通過(guò)命令行參數(shù)就能列出所有可安裝的SDK組件、按需安裝指定版本、自動(dòng)接受許可證協(xié)議這是自動(dòng)化構(gòu)建和容器化開(kāi)發(fā)環(huán)境里最有用的能力。1.2 哪些場(chǎng)景下你會(huì)真正需要它不是所有做Android開(kāi)發(fā)的人都需要單獨(dú)下載commandlinetools。我這里列幾個(gè)典型場(chǎng)景你可以對(duì)照判斷你主要用Android Studio開(kāi)發(fā)但CI服務(wù)器上跑的是命令行構(gòu)建需要在一臺(tái)沒(méi)有GUI的機(jī)器上安裝platform-tools、build-tools、platforms等組件。你正在用Flutter、React Native或Cordova做跨平臺(tái)開(kāi)發(fā)這些框架在首次編譯時(shí)需要自動(dòng)調(diào)用SDK組件手動(dòng)裝一個(gè)命令行工具比裝整個(gè)IDE輕量得多。你管理多臺(tái)開(kāi)發(fā)機(jī)希望把SDK安裝和升級(jí)過(guò)程沉淀成一套可復(fù)制的腳本而不是每臺(tái)機(jī)器都點(diǎn)一遍圖形界面。你只是需要adb、fastboot這類(lèi)基礎(chǔ)調(diào)試工具不需要完整的開(kāi)發(fā)IDE。在這些場(chǎng)景下一次性下載commandlinetools包然后用sdkmanager按需安裝組件是資源占用最低、可重復(fù)性最高的做法。1.3 文件名中的版本號(hào)如何解讀commandlinetools-mac-8092744_latest.zip這個(gè)文件名里每一段都有實(shí)際含義。mac標(biāo)明目標(biāo)平臺(tái)是macOS8092744是這次構(gòu)建的內(nèi)部版本號(hào)latest表示這是目前發(fā)布通道里的最新穩(wěn)定版。Google官方下載頁(yè)上的文件名格式通常類(lèi)似Linux和Windows平臺(tái)對(duì)應(yīng)的是commandlinetools-linux和commandlinetools-win版本號(hào)數(shù)字會(huì)隨每次構(gòu)建更新。需要注意的是8092744這個(gè)版本號(hào)與Android的API Level、Build Tools版本并不同步它只代表commandlinetools工具本身的迭代。也就是說(shuō)工具版本是最新的并不等于它會(huì)默認(rèn)捆綁或自動(dòng)安裝最新的platform和build-toolsSDK組件仍然需要通過(guò)sdkmanager另行安裝。2. 解壓前先看懂commandlinetools目錄結(jié)構(gòu)與工具分工2.1 壓縮包內(nèi)部結(jié)構(gòu)詳解把commandlinetools-mac-8092744_latest.zip下載下來(lái)后解壓會(huì)得到一個(gè)cmdline-tools目錄里面是bin、lib、source.properties等bin目錄下有sdkmanager、avdmanager、apkanalyzer、retrace等可執(zhí)行腳本lib目錄是這些腳本依賴的jar包。整體結(jié)構(gòu)很簡(jiǎn)潔但這恰恰是很多人第一步就踩坑的地方。sdkmanager在定位SDK根目錄時(shí)有嚴(yán)格的目錄層級(jí)約定。它期望你的SDK目錄下存在cmdline-tools/latest/bin這個(gè)路徑而不是直接解壓后隨手放一個(gè)cmdline-tools文件夾就算了。如果目錄結(jié)構(gòu)不對(duì)運(yùn)行sdkmanager時(shí)可能會(huì)報(bào)錯(cuò)提示無(wú)法確定SDK根目錄或者出現(xiàn)各種詭異的行為。這個(gè)細(xì)節(jié)不搞清楚后續(xù)所有命令都會(huì)別扭。2.2 四個(gè)主要命令的定位壓縮包bin目錄內(nèi)的幾個(gè)工具各司其職sdkmanager核心命令負(fù)責(zé)列出、安裝、卸載SDK組件管理許可證。avdmanager負(fù)責(zé)管理Android虛擬設(shè)備創(chuàng)建、刪除、列出AVD都靠它。apkanalyzer用來(lái)分析APK文件可以查看APK的清單信息、權(quán)限、大小構(gòu)成等。retrace配合混淆映射文件將混淆后的堆棧trace還原成可讀的類(lèi)名和方法名定位崩潰信息時(shí)非常有用。命令行場(chǎng)景下sdkmanager和avdmanager的使用頻率最高。前者是SDK組件管理的入口后者是在不裝Android Studio的情況下創(chuàng)建模擬器的唯一官方途徑。2.3 目錄規(guī)劃建議遵循的SDK布局為了讓后續(xù)操作順暢我建議你在Mac上規(guī)劃一個(gè)專(zhuān)門(mén)的SDK目錄例如~/android-sdk然后把所有平臺(tái)工具都?xì)w入這個(gè)統(tǒng)一目錄下。這樣做的原因是很多主流工具鏈如Flutter的Android SDK檢測(cè)、Gradle的本地SDK定位默認(rèn)會(huì)讀取ANDROID_HOME這個(gè)環(huán)境變量如果你的文件散落各處環(huán)境變量的配置就會(huì)很麻煩。一個(gè)合理的目錄結(jié)構(gòu)是這樣的~/android-sdk/ ├── cmdline-tools/ │ └── latest/ # 解壓后手動(dòng)構(gòu)建的層級(jí)結(jié)構(gòu) │ ├── bin/ │ ├── lib/ │ └── source.properties ├── platform-tools/ # adb、fastboot等 ├── platforms/ # 各版本Android平臺(tái) ├── build-tools/ # 各版本構(gòu)建工具 └── emulator/ # 模擬器相關(guān)把文件整理到這個(gè)狀態(tài)后后續(xù)寫(xiě)環(huán)境變量和腳本會(huì)輕松很多。3. 不裝Android Studio的Mac端完整配置流程3.1 檢查前置條件JDK版本要求在Mac上運(yùn)行sdkmanager之前必須先裝好JDK。sdkmanager是基于Java的命令行工具沒(méi)有JDK環(huán)境它根本無(wú)法啟動(dòng)。Java版本方面新版commandlinetools對(duì)JDK 17支持最完善官方文檔里也明確推薦使用JDK 17。如果你機(jī)器上仍然只有JDK 8或JDK 11建議先升級(jí)否則可能遇到啟動(dòng)報(bào)錯(cuò)。查看當(dāng)前Java版本的命令是java -version如果顯示的是17.0.x說(shuō)明滿足要求。如果沒(méi)裝JavaMac上最簡(jiǎn)單的安裝方式是先裝Homebrew然后執(zhí)行brew install --cask temurin17安裝完成后記得驗(yàn)證一下版本確保java -version能正確輸出。這一步?jīng)]做好的話后面sdkmanager會(huì)直接啟動(dòng)失敗。3.2 確定下載并解壓到正確的目錄層級(jí)先把壓縮包下載到本地任意目錄這一步可以直接用命令行完成curl -O https://dl.google.com/android/repository/commandlinetools-mac-8092744_latest.zip下載完成后建立SDK根目錄并把壓縮包解壓進(jìn)去。這里有個(gè)關(guān)鍵操作解壓得到的目錄名是cmdline-tools但sdkmanager要求這個(gè)目錄下面再做一層latest目錄所以你需要調(diào)整一下目錄結(jié)構(gòu)不能簡(jiǎn)單把所有文件直接丟到一個(gè)兩級(jí)目錄下。正確的做法mkdir -p ~/android-sdk/cmdline-tools unzip commandlinetools-mac-8092744_latest.zip -d ~/android-sdk/cmdline-tools mv ~/android-sdk/cmdline-tools/cmdline-tools ~/android-sdk/cmdline-tools/latest這三條命令做了三件事創(chuàng)建唯一的SDK根目錄、把壓縮包解壓到cmdline-tools目錄內(nèi)、再把內(nèi)部那個(gè)cmdline-tools子目錄重命名為latest。執(zhí)行完之后~/android-sdk/cmdline-tools/latest/bin/sdkmanager就是工具的完整路徑。這個(gè)重命名步驟是我在多次實(shí)踐后確認(rèn)的穩(wěn)妥方案。若不這樣做直接把解壓出來(lái)的cmdline-tools目錄當(dāng)作完整路徑sdkmanager運(yùn)行時(shí)會(huì)因?yàn)檎也坏筋A(yù)期路徑而報(bào)錯(cuò)。這不是玄學(xué)而是工具源碼里寫(xiě)死了路徑約定。3.3 配置環(huán)境變量zsh與bash的寫(xiě)法Mac目前默認(rèn)使用zsh作為Shell但仍有不少用戶切回了bash。無(wú)論你用的是哪一種配置思路是一致的把ANDROID_HOME指到SDK根目錄再把sdkmanager所在目錄加進(jìn)PATH。使用zsh的話在~/.zshrc里追加export ANDROID_HOME$HOME/android-sdk export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools使用bash的話在~/.bash_profile或~/.bashrc里追加同樣內(nèi)容。保存后不要忘記執(zhí)行source ~/.zshrc注意PATH里把platform-tools也加了進(jìn)去因?yàn)楹罄m(xù)通過(guò)sdkmanager安裝platform-tools之后adb命令會(huì)存放在這個(gè)目錄。提前加好后面就不用頻繁改動(dòng)環(huán)境變量了。配置完成后驗(yàn)證一下which sdkmanager sdkmanager --version如果命令能正常返回信息環(huán)境變量配置就算成功了。3.4 用sdkmanager安裝必備SDK組件到這里你的命令行工具已經(jīng)能正常運(yùn)行。接下來(lái)就是按需安裝SDK組件。先查看所有可用組件sdkmanager --list輸出會(huì)分為Installed packages和Available Packages兩大部分Available Packages里可以找到platforms、build-tools、platform-tools、emulator、system-images等所有組件。對(duì)于一個(gè)基礎(chǔ)的開(kāi)發(fā)或調(diào)試環(huán)境通常需要安裝sdkmanager --install platform-tools platforms;android-33 build-tools;33.0.1這條命令會(huì)安裝adb和fastbootplatform-tools、Android 13平臺(tái)platforms;android-33以及對(duì)應(yīng)版本的構(gòu)建工具。如果你需要更高版本比如android-34把版本號(hào)換掉即可也可以一次指定多個(gè)平臺(tái)。首次安裝時(shí)sdkmanager會(huì)提示你接受一些組件的許可協(xié)議。你可以逐個(gè)輸入y確認(rèn)也可以一次性全部接受sdkmanager --licenses輸入這個(gè)命令后它會(huì)把所有待接受的許可證列出來(lái)全部按y就行。自動(dòng)化腳本里如果想跳過(guò)交互可以通過(guò)管道把y批量喂給命令但手動(dòng)操作時(shí)直接執(zhí)行--licenses最省事。安裝完成后驗(yàn)證一下關(guān)鍵命令adb --version ls ~/android-sdk/platforms看到platforms目錄下生成android-33之類(lèi)的文件夾說(shuō)明組件安裝成功。3.5 創(chuàng)建與啟動(dòng)模擬器可選如果開(kāi)發(fā)過(guò)程中需要模擬器但你又不想裝Android Studioavdmanager可以幫你完成模擬器的創(chuàng)建和管理。首先要安裝一個(gè)系統(tǒng)鏡像例如sdkmanager --install system-images;android-33;google_apis;arm64-v8aMac芯片是Apple Silicon的話架構(gòu)選擇arm64-v8a如果是Intel芯片則選擇x86_64。裝好系統(tǒng)鏡像后創(chuàng)建AVDavdmanager create avd -n test_device -k system-images;android-33;google_apis;arm64-v8a創(chuàng)建完成后可以通過(guò)emulator -avd test_device啟動(dòng)模擬器但需要提前安裝emulator組件sdkmanager --install emulator這條鏈路走通之后你的Mac已經(jīng)成為一個(gè)不依賴Android Studio的完整Android開(kāi)發(fā)調(diào)試環(huán)境。4. 高頻問(wèn)題、報(bào)錯(cuò)排查與獨(dú)家避坑技巧4.1 常見(jiàn)問(wèn)題的定位與解決速查命令行工具用多了總會(huì)遇到各種報(bào)錯(cuò)。這里整理幾個(gè)出現(xiàn)頻率最高的問(wèn)題及其對(duì)策方便你快速定位問(wèn)題現(xiàn)象可能原因解決辦法運(yùn)行sdkmanager提示無(wú)法確定SDK根目錄cmdline-tools目錄層級(jí)不對(duì)缺少latest檢查~/android-sdk/cmdline-tools/latest/bin是否存在java.lang.NoClassDefFoundError或啟動(dòng)后閃退JDK版本過(guò)低或缺失安裝JDK 17并確認(rèn)java -version輸出正確sdkmanager下載組件時(shí)連接超時(shí)或緩慢網(wǎng)絡(luò)訪問(wèn)官方倉(cāng)庫(kù)不穩(wěn)定配置HTTP代理或換用國(guó)內(nèi)鏡像倉(cāng)庫(kù)安裝后adb命令找不到platform-tools未安裝或未加入PATH執(zhí)行sdkmanager --install platform-tools并檢查PATH環(huán)境變量設(shè)置后不生效沒(méi)有source配置文件或路徑寫(xiě)錯(cuò)執(zhí)行source ~/.zshrc重新打開(kāi)終端驗(yàn)證avdmanager創(chuàng)建AVD時(shí)報(bào)錯(cuò)system-images未找到系統(tǒng)鏡像未安裝或架構(gòu)與機(jī)器不匹配先sdkmanager --list確認(rèn)鏡像存在再安裝對(duì)應(yīng)架構(gòu)4.2 sdkmanager的許可證交互問(wèn)題新裝環(huán)境后第一次運(yùn)行--install最磨人的一次是許可證交互。你會(huì)在終端里看到一堆Accept? (y/N)提示如果安裝組件多可能要輸入很多次y。很多人在這里手一抖按錯(cuò)了字符安裝就中斷了前面下載的進(jìn)度全部白費(fèi)。我的建議是在安裝前先把許可證一并接受掉。sdkmanager --licenses這個(gè)命令會(huì)依次顯示所有待接受的許可協(xié)議你只需要持續(xù)按y回車(chē)。接受完成后再去執(zhí)行具體的安裝命令就不會(huì)突然卡住。如果你經(jīng)常重裝環(huán)境也可以把這一步寫(xiě)進(jìn)初始化腳本里避免每次手動(dòng)輸入。4.3 不同版本JDK的沖突與切換開(kāi)發(fā)機(jī)上裝了多個(gè)Java版本是常事sdkmanager對(duì)JDK版本敏感所以經(jīng)常出現(xiàn)明明java -version輸出正常sdkmanager卻說(shuō)Java版本不對(duì)的情況。這種沖突通常是因?yàn)橄到y(tǒng)默認(rèn)的java指向舊版本或者sdkmanager腳本內(nèi)部用到的JAVA_HOME沒(méi)有指向預(yù)期版本。解決思路有兩種。第一種是臨時(shí)指定執(zhí)行sdkmanager之前手動(dòng)設(shè)置JAVA_HOME指向JDK 17的安裝目錄。第二種是在~/.zshrc里統(tǒng)一管理JAVA_HOME用Homebrew裝好temurin17后通常路徑是export JAVA_HOME/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home設(shè)置完以后重新source配置文件再運(yùn)行sdkmanager基本不會(huì)出現(xiàn)版本沖突。4.4 下載慢、超時(shí)的實(shí)用對(duì)策sdkmanager從官方倉(cāng)庫(kù)拉取組件時(shí)如果網(wǎng)絡(luò)環(huán)境不理想容易超時(shí)甚至失敗。這里有兩個(gè)比較實(shí)用的處理辦法。第一個(gè)是給sdkmanager配置HTTP代理。如果你本機(jī)或公司網(wǎng)絡(luò)有可用的代理端口可以在運(yùn)行命令前臨時(shí)指定代理環(huán)境變量export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890設(shè)置代理后下載速度通常會(huì)有明顯改善。如果sdkmanager仍然很慢可以考慮使用國(guó)內(nèi)鏡像倉(cāng)庫(kù)。Android SDK的組件清單其實(shí)是一個(gè)XML文件sdkmanager支持通過(guò)參數(shù)指定倉(cāng)庫(kù)地址但具體操作會(huì)因版本略有差異。穩(wěn)妥的做法是直接用官方倉(cāng)庫(kù)加代理成功率相對(duì)最高。第二個(gè)辦法是錯(cuò)峰下載。Android SDK官方倉(cāng)庫(kù)在部分地區(qū)高峰期訪問(wèn)速度確實(shí)一般嘗試在非高峰時(shí)段執(zhí)行安裝命令或者采用重試策略也能緩解問(wèn)題。在CI環(huán)境里我會(huì)把sdkmanager --install包在一個(gè)帶重試的shell函數(shù)里避免一次失敗就打斷整個(gè)構(gòu)建。4.5 環(huán)境變量在子終端不生效的處理Mac上很多人在終端里配好了環(huán)境變量但每次新開(kāi)一個(gè)終端窗口命令又找不到了。這個(gè)問(wèn)題很常見(jiàn)原因多半是配置文件寫(xiě)錯(cuò)了位置或者新終端沒(méi)有加載對(duì)應(yīng)配置。需要注意zsh會(huì)在啟動(dòng)時(shí)加載~/.zshrcbash則會(huì)加載~/.bash_profile或~/.bashrc。如果你把環(huán)境變量寫(xiě)進(jìn)~/.zshrc以后又切回bash新開(kāi)的bash終端就不會(huì)自動(dòng)生效。同理只在~/.bash_profile里配置zsh終端也不會(huì)加載。我的建議是明確自己主用的Shell把環(huán)境變量寫(xiě)進(jìn)對(duì)應(yīng)配置文件這樣新終端窗口才會(huì)自動(dòng)生效。如果實(shí)在不想糾結(jié)可以在~/.zprofile里也放一份同樣的配置它是macOS上跨Shell兼容性相對(duì)較好的方案。4.6 關(guān)于macOS安全策略對(duì)解壓工具的攔截在Mac上解壓第三方zip包時(shí)偶爾會(huì)遇到系統(tǒng)提示無(wú)法打開(kāi)因?yàn)闊o(wú)法驗(yàn)證開(kāi)發(fā)者之類(lèi)的安全攔截。這通常發(fā)生在直接雙擊某些GUI工具時(shí)對(duì)命令行解壓方式一般影響不大。如果你在終端用unzip命令解壓時(shí)遇到了權(quán)限或安全策略相關(guān)報(bào)錯(cuò)可以嘗試先移除文件的隔離屬性xattr -d com.apple.quarantine commandlinetools-mac-8092744_latest.zip然后再解壓。這個(gè)操作清除掉下載文件的隔離標(biāo)記后系統(tǒng)就不會(huì)再做額外的安全策略攔截了。Google官方的命令行工具本身是可信的這里的前提是你從官方渠道下載文件校驗(yàn)值確認(rèn)無(wú)誤。4.7 自動(dòng)化構(gòu)建環(huán)境中的注意事項(xiàng)如果你是在CI或Docker環(huán)境里使用commandlinetools有幾個(gè)細(xì)節(jié)值得特別注意。第一CI環(huán)境中通常沒(méi)有交互式終端--licenses會(huì)因?yàn)闆](méi)有標(biāo)準(zhǔn)輸入而卡住所以必須通過(guò)yes | sdkmanager --licenses這種方式把輸入提前喂進(jìn)去。第二sdkmanager在下載組件時(shí)會(huì)寫(xiě)日志到當(dāng)前目錄如果CI的工作目錄權(quán)限受限可能會(huì)報(bào)錯(cuò)建議把工作目錄切到有寫(xiě)權(quán)限的路徑。第三如果需要緩存下載內(nèi)容、加速多次構(gòu)建可以保留sdkmanager的緩存目錄避免每次全量下載。這些細(xì)節(jié)在本地手動(dòng)搭建環(huán)境時(shí)不容易暴露但在自動(dòng)化流水線里每一個(gè)都可能讓構(gòu)建卡上幾十分鐘提前處理好能省下不少排查時(shí)間。5. 自己搭建過(guò)一次后的一些體會(huì)從解壓這個(gè)壓縮包到跑通完整鏈路我前后也折騰過(guò)不少來(lái)回。最大的心得是commandlinetools雖然看起來(lái)只是一個(gè)小工具包但它把Android SDK的安裝和管理邏輯完全暴露給了開(kāi)發(fā)者。理解了cmdline-tools/latest這個(gè)目錄層級(jí)的意義理解了sdkmanager的組件命名規(guī)則比如platforms;android-33里的分號(hào)你就不再依賴IDE幫你做所有事寫(xiě)腳本、配CI、快速?gòu)?fù)現(xiàn)構(gòu)建環(huán)境都會(huì)順暢很多。最后再分享一個(gè)小技巧如果你經(jīng)常在不同電腦之間遷移開(kāi)發(fā)環(huán)境可以讓sdkmanager把已安裝的組件列表導(dǎo)出然后在另一臺(tái)機(jī)器上用腳本一鍵重建。這個(gè)思路比每次手動(dòng)挨個(gè)安裝組件高效得多也讓命令行工具的價(jià)值被真正放大了。本文還有配套的精品資源點(diǎn)擊獲取