凡是接触过 Android 开发的人大概率都被 Android SDK 的下载和安装磨掉过耐心。我最初配环境那会儿面对 SDK Manager 里一堆包名完全不知道该勾选哪些下载到一半进度条卡住装完之后 adb 又提示 command not found前前后后折腾了一下午。后来把组件之间的关系理清楚再配合镜像源和硬件加速方案整套流程十分钟内就能走通。这篇文章就把 Android SDK 从下载、安装到环境变量配置的完整链路拆开讲包括 SDK Manager 里找不到 HAXM 时的正确应对方式适合刚入门 Android 开发、或者换新电脑后需要重建开发环境的同学参考。1. 先搞清楚你下载的到底是一堆什么组件很多人以为 Android SDK 就是一个安装包下载完装一下就算完事。真实情况是它是一个庞大的工具集合不同工具服务于不同阶段编译、打包、调试、运行模拟器各管各的。这一步不搞清楚后面安装时很容易多装很多用不到的东西或者漏掉关键组件导致项目跑不起来。1.1 Android SDK 不是“一个包”而是一组工具SDK 里最常见的组件包括Command Line Tools提供 sdkmanager、avdmanager 等命令行入口、Platform-Tools提供 adb、fastboot、SDK Platform对应不同 Android API Level 的编译依赖、Build-Tools负责打包资源、生成最终 APK、Emulator 和 System Images模拟器程序与系统镜像以及一些可选加速组件。组件名主要作用属于必装吗commandlinetools提供 sdkmanager、avdmanager用于安装和管理其他组件必装它是入口platform-toolsadb、fastboot连接真机和模拟器的核心工具必装platforms;android-XX每个 API Level 对应的 android.jar编译时依赖按项目需要装build-tools;XX.X.X资源编译、打包、签名工具比如 aapt2、zipalign按项目需要装emulator system-images虚拟设备运行的程序和系统镜像需要模拟器才装extras;google;...模拟器硬件加速驱动、USB 驱动等需要模拟器加速才装这里最容易踩的坑是“把每个 API Level 都装一遍”。我见过有同事把 Android 26 到 34 的 platforms 全部勾上磁盘空间白白占用十几个 GB实际项目里根本用不到那么多。正确的做法是先看项目的compileSdkVersion和targetSdkVersion只装对应版本。比如项目用的是compileSdkVersion 33那就只装platforms;android-33后续需要更高版本时再补。1.2 先决定是装完整 Android Studio 还是只装命令行工具这一步直接影响你后面的下载方式。如果你是纯 Android 应用开发新手建议直接下载 Android Studio它自带 SDK Manager 和 AVD ManagerUI 界面里勾一勾就能完成大部分安装工作。但如果你是后端写 CI 脚本、还在用 IntelliJ IDEA 或 VS Code 开发 Android、或者单纯想自己掌控 SDK 目录那只需要下载官方提供的 Command Line Tools。命令行工具更轻量不携带 IDE 那一大堆依赖也更容易在自动化环境里复现。我个人的习惯是开发机上装 Android Studio 来管理模拟器和 SDK但构建机或临时环境只装 commandlinetools通过脚本完成 SDK 安装。这样同一套环境可以在本机和 CI 之间保持一致避免“在我电脑上能跑在服务器上跑不了”的尴尬。无论哪种方式都要先确认电脑满足最低要求64 位操作系统JDK 版本与你的构建工具匹配AGP 8.x 通常要求 JDK 17磁盘预留至少 10 GB 空间。还要注意 SDK 目录不要放在带空格的路径里也不要放在中文路径下后续很多工具对路径空格敏感纯英文目录能省掉很多莫名其妙的坑。2. 从官网下载 Command Line Tools 并一步步安装组件这里以“只装命令行工具”为例因为这条链路覆盖了 SDK 下载、目录规划、环境变量配置的完整过程理解了它用 Android Studio 时自然也就明白界面里每个选项在干什么。2.1 拿到官方命令行工具压缩包先去 Android 开发者官网找到 Command line tools only 区域也就是大家常说的 “androidsdk下载官网”入口。根据系统选择对应的压缩包Windows 选commandlinetools-win-XXXX_latest.zipmacOS 选commandlinetools-mac-XXXX_latest.zipLinux 选commandlinetools-linux-XXXX_latest.zip这里有一个非常容易踩的坑解压后不要直接双击运行sdkmanager。新版命令行工具对自身路径有严格约定它要求完整路径必须是SDK根目录/cmdline-tools/latest/bin/sdkmanager否则启动时会报Error: Could not find or load main class这类错误。正确的做法是先建一个 SDK 根目录比如D:\Android\Sdk解压出来的文件夹默认叫cmdline-tools把它整个放进D:\Android\Sdk\cmdline-tools然后重命名为latest最终目录长成这样D:\Android\Sdk\cmdline-tools\latest\bin\sdkmanager.bat我第一次用的时候就是直接解压到桌面运行结果怎么都报错后来才发现是目录层级不对。新版工具的目录检查逻辑就是这么“轴”提前把目录结构排好后面会顺利很多。2.2 用 sdkmanager 安装 platform-tools 和 platform确认目录结构正确后进入cmdline-tools\latest\bin先看有哪些包可以装# Windows 进入目录后 cd D:\Android\Sdk\cmdline-tools\latest\bin # 查看所有可安装组件 sdkmanager.bat --list # 如果 sdkmanager 不在预期目录也可以通过 --sdk_root 指定根目录 sdkmanager.bat --sdk_rootD:\Android\Sdk --list--sdk_root这个参数很关键。因为 sdkmanager 是根据自己的位置推断 SDK 根目录的如果你把cmdline-tools放在了非标准位置不带这个参数会导致后续安装的组件全部落到错误路径下。安装核心组件sdkmanager.bat --sdk_rootD:\Android\Sdk --install platform-tools platforms;android-33 build-tools;33.0.2这条命令会依次下载并解压 platform-tools、android-33 平台文件和 33.0.2 版构建工具。如果只要开发一个普通项目以上三个组件基本够用需要跑模拟器时再补sdkmanager.bat --sdk_rootD:\Android\Sdk --install emulator system-images;android-33;google_apis;x86_64安装完组件后还有一个很多人会漏掉的步骤接受许可证。Gradle 构建的时候如果报You have not accepted the license agreements百分之百是这一步没做。sdkmanager.bat --sdk_rootD:\Android\Sdk --licenses执行后会出现一堆许可证协议一路输入y确认就行。不想一条条手输的话yes | sdkmanager.bat --sdk_rootD:\Android\Sdk --licenses在 Windows 的 CMD 里未必有效PowerShell 或 Git Bash 里是可以的建议还是老老实实按几次 y顺便看一眼许可内容。2.3 配置环境变量 ANDROID_HOME 和 PATH组件安装完后最后一个环节是让系统的命令窗口能直接识别adb、sdkmanager这些命令。需要配置的环境变量有两个ANDROID_HOME指向 SDK 根目录也就是D:\Android\SdkPATH追加两个子目录分别是%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\cmdline-tools\latest\binWindows 设置方法右键“此电脑” - 属性 - 高级系统设置 - 环境变量在系统变量里新建ANDROID_HOME再编辑Path追加上面两个目录。设置完必须重新打开终端才生效。macOS 或 Linux 则在~/.bashrc或~/.zshrc里追加export ANDROID_HOME$HOME/Android/Sdk export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin配置完成后验证一下sdkmanager --version adb --version如果这两个命令都能输出版本信息说明 SDK 的工具链已经能正常工作了。2.4 让 Android Studio 和命令行共用同一个 SDK如果你计划同时使用 Android Studio 和命令行工具建议让 IDE 指向同一个 SDK 目录避免重复下载两套 SDK。打开 Android Studio进入 Settings / Preferences - Appearance Behavior - System Settings - Android SDK把 Android SDK Location 改到D:\Android\Sdk即可。当从命令行构建一个已有的 Android 项目时项目根目录下的local.properties文件会决定 Gradle 使用哪个 SDKsdk.dirD:/Android/Sdk注意 Windows 路径中反斜杠需要转义用正斜杠更省心。这个文件不会提交到版本控制每个开发机都要单独配置很多项目换个人就编译不过多半是这里没有配对。3. 官方下载太慢时怎么用镜像源把速度提上来SDK 组件的默认下载地址是在官方服务器上部分网络环境下速度波动大进度条卡在 0% 是常有的事。如果你也遇到这种情况别急着反复重试先判断是网络问题还是本身在下载大文件再选择合适的处理方式。3.1 先判断是真卡住还是假卡住sdkmanager下载时的进度条不一定每秒都在动尤其是下载几个 GB 的 system image 时解压阶段可能看起来像卡住了。建议给一个包至少 3 到 5 分钟的观察时间如果进度条完全不动、网卡流量也几乎为 0再考虑中断重试。重试之前可以先删掉 SDK 根目录下残留的临时文件# Windows rd /s /q D:\Android\Sdk\.temp # macoS / Linux rm -rf ~/Android/Sdk/.tempsdkmanager会把下载中的临时文件放在.temp目录异常中断后残留文件可能导致下一次下载一直卡在解析阶段。清掉临时目录后重新执行安装命令大多数情况下能恢复正常。3.2 手动从官方仓库 XML 里找到组件压缩包如果你要下载的组件特别大比如 system-images 动辄 1 GB 以上命令行工具的下载速度不理想时可以手动从官方仓库索引里定位压缩包再用普通下载方式拉下来。SDK 组件列表存在一个 XML 文件里地址是https://dl.google.com/android/repository/repository2-1.xml用浏览器打开后搜索你需要的组件名比如platforms;android-33附近会出现一组url标签里面的文件名就是该组件的压缩包名https://dl.google.com/android/repository/platform-33_r02.zip拿到直链后用浏览器或下载工具把它下下来。然后按 SDK 目录结构手动解压platform-33_r02.zip解压后要放到SDK/platforms/android-33/目录里包含android.jar、build.prop等文件build-tools_r33.0.2-windows.zip解压后放到SDK/build-tools/33.0.2/系统镜像通常解压后里面有system.img、userdata.img要放进SDK/system-images/android-33/google_apis/x86_64/这种方式不需要依赖任何第三方工具只是把 sdkmanager 做的事手工做了一遍。目录结构一旦放对sdkmanager 再执行--list_installed时就能识别出来。3.3 使用国内云厂商的镜像源除了手动方式另一个思路是使用国内云厂商提供的 Android SDK 镜像。阿里云和腾讯云都维护过对应的镜像页搜索“阿里云 Android SDK 镜像”或“腾讯云 Android SDK 镜像”就能找到入口。镜像站通常覆盖官方仓库里最常见的组件版本但不是所有版本都全。使用镜像源时我的建议是优先选择与官方 repository XML 中文件名一致的版本如果镜像站的版本列表不完整不要硬凑缺什么组件就回官方仓库下载镜像源适合加速下载不适合作为长期唯一的组件来源还有个很多人忽视的点Android 项目构建时不仅下载 SDK还要从 Google 的 Maven 仓库拉取 AndroidX、Jetpack 等依赖。这个下载也可能很慢但可以通过在项目build.gradle里配置镜像仓库来解决repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() }这段配置放在allprojects或dependencyResolutionManagement下都可以。Maven 镜像的更新通常比官方源慢一点偶尔会出现某个版本在镜像上不存在的情况所以我把google()和mavenCentral()也保留在后面找不到时仍可以自动回退到官方源。3.4 校验下载文件的完整性无论从哪个渠道下载 SDK 组件都建议校验一下压缩包的哈希值避免文件损坏导致解压后构建报出一堆难以解释的错误。官方 repository2-1.xml 里每个组件都带有checksum常见的是 SHA1 或 SHA256。Windows PowerShell 下用Get-FileHash .\platform-33_r02.zip -Algorithm SHA256Linux 或 macOS 下用sha256sum platform-33_r02.zip将计算结果和 XML 中标注的值比对一下一致再解压。这一步很基础但能过滤掉大量后续开发中的“玄学问题”。4. SDK Manager 里找不到 HAXM别找它是被时代淘汰的组件“androidsdk 中没有 haxm”这几年几乎是搜索常客。很多人一边看老教程一边对着新版 SDK Manager 找 HAXM 安装项最后的结果自然是找不到。这很正常因为 Google 已经逐渐把 HAXM 从标准 SDK 分发里移除了这不是你的操作问题。4.1 HAXM 是什么为什么退出历史舞台HAXM 全称 Intel Hardware Accelerated Execution Manager是 Intel 提供的一个轻量级虚拟化驱动早期 Android 模拟器在 x86 平台上流畅运行基本都靠它。它的作用相当于一个专门给模拟器用的 Hypervisor负责把模拟器里的指令直接调度到 CPU 硬件虚拟化能力上避免纯软件模拟带来的巨大性能损耗。但随着模拟器迭代Google 开始推广自己的 Android Emulator Hypervisor DriverAEHD并且 Windows 平台上的微软 Hypervisor 方案也在逐步成熟。HAXM 从维护到分发都显得越来越边缘化最终在新版本里被移出 SDK Manager 的可选项。之前的版本中老教程里写的“Intel x86 Emulator Accelerator (HAXM installer)”只在extras分类下出现过而新版 SDK Manager 中这个分类下的内容已经大幅调整。所以当你打开新版 SDK Manager发现找不到 HAXM 时不要急着按老教程去下载一个独立安装包强行装。HAXM 与新版模拟器、新版 Windows 的虚拟化栈之间兼容性并不好强行安装后有概率出现蓝屏或模拟器无法启动的后续问题。4.2 先检查 CPU 虚拟化开关是否打开无论使用哪种加速方案前提都是 CPU 的虚拟化功能已经在 BIOS/UEFI 里开启。这一步没做后面每个方案都会失败。Windows 上最简单的检查方式打开任务管理器 - 性能 - CPU看右下角“虚拟化”这一栏是“已启用”还是“已禁用”。如果是禁用状态需要重启电脑在 BIOS/UEFI 设置里找到虚拟化选项Intel 平台通常叫 Intel Virtualization Technology也就是 VT-xAMD 平台通常叫 SVM Mode有的 BIOS 显示为 AMD-V开启并保存重启后再回到任务管理器确认状态。这一步虽然看起来基础但经常被人忽略特别是某些笔记本出厂默认关闭虚拟化导致模拟器一直报x86_64 emulation currently requires hardware acceleration。4.3 按 CPU 平台和系统状态选择加速方案确认虚拟化开启后下一步不是盲目装软件而是看你的系统里是否已经启用了 Hyper-V 或 Windows 虚拟机监控程序平台。这里有个关键逻辑AEHD/HAXM 与 Hyper-V 不共存两者都会占用 CPU 虚拟化能力而 Windows 自带的 WHPX 是在 Hyper-V 基础上给模拟器提供加速接口的。平台系统状态推荐加速方案Intel CPU未启用 Hyper-VAEHD通过 sdkmanager 安装 extras 包Intel CPU已启用 Hyper-V / WHPX启用 Windows Hypervisor Platform模拟器走 WHPXAMD CPU未启用 Hyper-V优先启用 Windows Hypervisor Platform或尝试 AEHDAMD CPU已启用 Hyper-V / WHPX启用 Windows Hypervisor Platform模拟器走 WHPXmacOS—无需额外驱动模拟器使用系统自带 Hypervisor.frameworkLinux—确保 KVM 可用即/dev/kvm存在AEHD 的安装方式是先用 sdkmanager 安装对应 extras 包sdkmanager.bat --install extras;google;Android_Emulator_Hypervisor_Driver安装成功后在SDK\extras\google\Android_Emulator_Hypervisor_Driver目录下找到silent_install.bat以管理员身份运行silent_install.bat如果你的 sdkmanager 里列不出这个包也可以从官方 repository2-1.xml 里找到对应的 zip 手动下载安装思路和前面一致。如果你用的是 Windows 10/11并且系统里已经开启了 Hyper-V那更推荐直接启用“Windows Hypervisor Platform”功能让模拟器走微软官方提供的 WHPX 后端。操作路径是控制面板 - 程序 - 启用或关闭 Windows 功能勾选“Windows 虚拟机监控程序平台”重启后模拟器会自动识别。4.4 模拟器加速失效的常见排查链路我自己的习惯是只要模拟器启动异常先跑一次检查命令看加速后端到底处于什么状态# 进入模拟器目录 cd D:\Android\Sdk\emulator # 检查当前加速状态 emulator.exe -accel-check输出结果里如果包含HAXM is not installed或AEHD is not installed说明驱动缺失如果提示hypervisor is enabled说明 WHPX 或其他 hypervisor 后台在正常工作。还有一种常见报错是VT-x is being used by another hypervisor。这通常意味着 Hyper-V 或虚拟机监控程序占用了虚拟化能力而你又尝试安装 AEHD/HAXM。解决方式有两种一是回到 Windows 功能里关闭 Hyper-V 相关选项重启后再装 AEHD二是保留 Hyper-V不装 AEHD/HAXM直接启用“Windows Hypervisor Platform”功能让模拟器走 WHPX。如果确认要关闭 Hyper-V也可以在管理员 CMD 里执行bcdedit /set hypervisorlaunchtype off然后重启。这个命令的效果是关闭 Windows 引导时的虚拟机监控程序加载注意修改启动配置前务必备份数据不要在自己还需要 Docker、WSL 等 Hyper-V 功能的机器上盲目执行。关了之后 Docker Desktop 这类依赖 Hyper-V 的工具会无法启动这也是很多开发者踩过的坑。模拟器加速和 SDK 本身不是同一个问题但实际体验中加速配置好坏直接决定你开发时的心情。没有加速的 x86 模拟器卡到连点一个按钮都要转三秒圈配置好之后基本接近真机流畅度。5. 装完 SDK 后必踩的坑和一套自检清单SDK 安装完成不代表所有事情都结束了。即便上面的步骤全部走完真正用起来还是会遇到几个几乎每个人都会碰上的小毛病我干脆把最常见的几种和对应排查方式整理一下。5.1 adb command not found新开一个终端窗口输入adb version结果提示 command not found。这个问题八成出在 PATH 配置上。检查一下%ANDROID_HOME%\platform-tools是否确实追加到了 PATH并且重新打开了终端。Windows 的环境变量修改不会自动刷新到已经打开的命令窗口里必须新开一个。还有一种隐蔽情况系统里装了某些手机助手或杂七杂八的工具这些工具自带 adb并且把它的目录放在了 PATH 前面。此时你执行adb version看到的可能不是 Google 官方版本后面连接设备时会报adb server version doesnt match this client。解决方式是用命令查看 adb 实际路径where.exe adb如果指向的不是自己的 SDK 目录把 SDK 的platform-tools在 PATH 中的位置提到最前或者干脆卸载那些杂牌工具。官方 adb 的版本输出一般带有Android Debug Bridge version 1.0.41 Version 33.x.x之类信息遇到奇怪的版本号就要留个心眼。5.2 许可证未接受与多 SDK 路径冲突Gradle 构建时如果报You have not accepted the license agreements of the following SDK components:即使之前执行过sdkmanager --licenses问题也可能再出现。最常见的原因是你项目里有两个 SDK 位置IDE 或 Gradle 实际使用的是另一个目录。检查项目根目录的local.properties确认sdk.dir指向的是你接受过许可证的那个 SDK。如果 IDE 配置的 SDK 路径和命令行安装的 SDK 路径不一致就会出现“我在命令行接受过许可了怎么构建还报错”的诡异情况。另外sdkmanager --licenses执行完成后再用sdkmanager --list_installed确认一下确保当前路径下的 SDK 就是项目使用的 SDK。5.3 模拟器启动失败或 adb 端口被占用模拟器启动后一直显示 offline或者adb devices里看不到设备很多时候不是 SDK 问题而是 adb 服务本身出了问题。先尝试重启 adbadb kill-server adb start-server adb devices如果还是不行检查 5037 端口是否被其他进程占用。Windows 下用netstat -ano | findstr 5037找到 PID 后到任务管理器里确认这个进程是什么。如果是一个旧的 adb.exe结束掉再重启 adb 服务即可。如果占用进程是某个手机助手的服务大概率它也在抢 adb 服务这种环境下真机调试会持续抽风建议直接卸载。模拟器里还有一个常见坑AVD 选用了 ARM 架构的 system image在 x86 电脑上运行会慢到怀疑人生。新建 AVD 时一定要选x86或x86_64的系统镜像并且启动前检查加速后端是否可用。5.4 用一条命令验证 SDK 是否完整环境配好后我习惯先把已安装组件列出来检查一遍sdkmanager --list_installed看到platform-tools、platforms;android-33、build-tools;33.0.2这些关键条目都出现后再打开或新建一个空项目让 Gradle 完整跑一遍编译、打包、安装到模拟器或真机的流程。这一步能通过说明 SDK 下载、安装、环境变量、许可证、硬件加速整套链路都是通的。最后分享一个小习惯每次安装新的 SDK 组件前我都会先看一下磁盘剩余空间然后顺手把.temp目录清理一次。这套 SDK 环境配好之后能用很久但最忌讳的就是网络不稳定时反复中断安装导致残留文件堆积与其出问题再排查不如在开始时就把目录结构和管理方式理顺。