Android 开发环境搭建指南

- [1. 版本清单](#1. 版本清单)
- [2. 下载清单](#2. 下载清单)
- [3. 安装步骤](#3. 安装步骤)
- - [3.1 解压](#3.1 解压)
  - [3.2 设置用户级环境变量(PowerShell)](#3.2 设置用户级环境变量(PowerShell))
  - [3.3 安装 SDK 组件并接受许可](#3.3 安装 SDK 组件并接受许可)
- [4. 验证清单](#4. 验证清单)
- [5. 踩坑记录:adb 所有命令永久卡死(本机环境特有)](#5. 踩坑记录:adb 所有命令永久卡死(本机环境特有))
- [6. 可选:创建模拟器](#6. 可选:创建模拟器)
- [7. 网络注意事项](#7. 网络注意事项)

本文档记录 2026-11-01 在本机完成的完整搭建过程,供在其他机器 上手动复现。

全部使用免安装 zip 解压方案,不依赖安装器,路径可控、可整体迁移。

1. 版本清单

组件	版本	安装位置
JDK	Temurin 21.0.13+9 (LTS)	`D:\dev\jdk\jdk-21.0.13+9`
Android Studio	rabbit2(解压版)	`D:\dev\android-studio`
Gradle	9.8.2	`D:\dev\gradle`
Android SDK	---	`D:\dev\android-sdk`
Gradle 用户缓存	---	`D:\dev\.gradle`

SDK 已装组件:

复制代码

build-tools;36.0.0        emulator            platform-tools;37.0.1
platforms;android-35      platforms;android-36
system-images;android-36;google_apis;x86_64   (模拟器系统镜像,可选)
cmdline-tools;latest

2. 下载清单

文件	来源
OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip	https://api.adoptium.net/v3/binary/latest/21/ga/windows/x64/jdk/hotspot/normal/eclipse
android-studio-rabbit2-windows.zip	https://developer.android.com/studio (Windows zip 免安装版)
gradle-9.8.2-bin.zip	https://services.gradle.org/distributions/gradle-9.8.2-bin.zip
commandlinetools-win-15859902_latest.zip	https://dl.google.com/android/repository/commandlinetools-win-15859902_latest.zip

3. 安装步骤

3.1 解压

bash 复制代码

# 在 D:\dev\downloads 存放四个 zip 后:
unzip -q downloads/OpenJDK21U-jdk_x64_windows_hotspot_21.0.13_9.zip -d /d/dev/jdk
unzip -q downloads/android-studio-rabbit2-windows.zip -d /d/dev/
mv /d/dev/android-studio-* /d/dev/android-studio   # 视解压出的目录名调整
unzip -q -o downloads/gradle-9.8.2-bin.zip -d /d/dev/gradle-tmp
mv /d/dev/gradle-tmp/gradle-9.8.2 /d/dev/gradle
unzip -q downloads/commandlinetools-win-15859902_latest.zip -d /d/dev/android-sdk/
mkdir -p /d/dev/android-sdk/cmdline-tools
mv /d/dev/android-sdk/cmdline-tools /d/dev/android-sdk/cmdline-tools-tmp
mv /d/dev/android-sdk/cmdline-tools-tmp /d/dev/android-sdk/cmdline-tools/latest
# 注意: cmdline-tools 解压出来叫 cmdline-tools,必须挪到 latest 子目录,否则 sdkmanager 找不到

3.2 设置用户级环境变量(PowerShell)

powershell 复制代码

[Environment]::SetEnvironmentVariable('JAVA_HOME','D:\dev\jdk\jdk-21.0.13+9','User')
[Environment]::SetEnvironmentVariable('ANDROID_HOME','D:\dev\android-sdk','User')
[Environment]::SetEnvironmentVariable('GRADLE_USER_HOME','D:\dev\.gradle','User')

# 追加 Path(先读旧值再追加,避免覆盖)
$p = [Environment]::GetEnvironmentVariable('Path','User')
$add = 'D:\dev\jdk\jdk-21.0.13+9\bin;D:\dev\android-sdk\platform-tools;D:\dev\android-sdk\cmdline-tools\latest\bin;D:\dev\gradle\bin;D:\dev\android-studio\bin'
[Environment]::SetEnvironmentVariable('Path', "$p;$add", 'User')

设置后重开终端生效。

3.3 安装 SDK 组件并接受许可

bash 复制代码

export JAVA_HOME="D:\dev\jdk\jdk-21.0.13+9"

sdkmanager --licenses                                  # 一路输 y
sdkmanager "platform-tools" "platforms;android-35" "platforms;android-36" \
           "build-tools;36.0.0" "emulator" \
           "system-images;android-36;google_apis;x86_64"   # 系统镜像约1.3GB,可选

4. 验证清单

bash 复制代码

java -version           # 应显示 21.0.13
gradle --version        # Launcher JVM 应为 21.0.13
adb devices             # 应输出 "List of devices attached"(即使为空)
sdkmanager --list_installed   # 核对组件表
studio64.exe            # Android Studio 首次启动向导,SDK路径指向 D:\dev\android-sdk

5. 踩坑记录:adb 所有命令永久卡死(本机环境特有)

现象

adb devices、甚至 adb kill-server 都无限挂起,无任何报错;重启后必现。

根因

本机安全软件/防火墙对未监听端口静默丢包(不回 RST)。验证方法:

bash 复制代码

curl -m 5 http://127.0.0.1:5037/ ; echo $?    # 期望 exit=7(拒绝),实际 exit=28(超时)=异常

adb 客户端启动时先探测 127.0.0.1:5037,靠"连接被拒"判断 server 不存在,然后拉起 server。

探测包被静默丢弃后客户端永远等不到结果 → 所有 adb 命令卡死。

绕过修复

立即修复(server 常驻,端口有监听后探测正常):

bash 复制代码

adb nodaemon server &    # 或: adb fork-server server
netstat -ano | grep 5037 # 确认 LISTENING
adb devices              # 秒回

永久修复 (开机自启,需自己执行------写入启动目录的操作被本会话安全策略拦截):

把以下内容保存为 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\adb-server-startup.vbs:

vbs 复制代码

CreateObject("WScript.Shell").Run "cmd /c ""D:\dev\android-sdk\platform-tools\adb.exe"" fork-server server", 0, False

根治(推荐找 IT):在安全客户端(疑似天擎 EDR)放行 adb.exe,或关闭对回环 closed-port 的 stealth drop。

6. 可选:创建模拟器

bash 复制代码

avdmanager create avd -n api36 -k "system-images;android-36;google_apis;x86_64"
# 注意: 不要加 -d pixel_7 之类的设备定义,新版 avdmanager 会因 devices.xml 加载失败
#       导致 config.ini 里出现 avd.name=<build> 占位符(实测不影响启动,但配置不干净)
echo no | avdmanager create avd ...   # 交互询问自定义硬件配置时回答 no

启动验证(本机实测通过):

bash 复制代码

emulator -avd api36 -no-window -gpu swiftshader_indirect   # 无头测试
adb devices     # 出现 emulator-5554,约2分钟后 getprop sys.boot_completed 返回 1
adb -s emulator-5554 emu kill   # 关闭

首次启动前确认 Windows 已启用虚拟化(任务管理器→性能→虚拟化:已启用;

控制面板→启用或关闭 Windows 功能→"虚拟机平台"勾选)。

本机实测 emulator -accel-check 显示 WHPX 可用,冷启动无头引导约 141 秒。

已知小问题(可忽略):avdmanager list avd 正常显示 api36,但

config.ini 中 avd.name=<build>、Failed to process emu-update-last-check.ini

均为无害告警。

7. 网络注意事项

API 网关 ai-gateway.qianxin-inc.cn 直连可用,无代理。
已知问题:首次 TLS 握手偶发 10s+(中间设备抖动),重试即可。