Android Studio
Android Studio 最容易制造一种假象：IDE 能打开，项目就算搭好了。真正进入构建时，问题才依次出现：模拟器没有硬件加速、SDK package 不完整、Studio 与 AGP 不兼容、IDE 和终端使用不同 JDK、ADB 看到设备却没有授权，或者一次自动升级同时改了五层工具链。
先把对象拆开。Android Studio 是 IDE；Android Gradle Plugin（AGP）把 Android 构建能力接入 Gradle；Gradle Wrapper 决定 Gradle 版本；JDK 分别承担启动 IDE、运行 Gradle 和编译 Java 源码；Android SDK 提供 platform、build-tools、platform-tools 与 emulator；AVD 是模拟设备配置；ADB 是主机与设备之间的调试桥。任何一层漂移，都可能表现成“Sync failed”，但每一层的证据和回滚动作完全不同。
先判断开发机能不能承担模拟器
先确认机器是否适合本地模拟器。Android Studio 安装要求会分别给出只运行 Studio 和同时运行 Emulator 的资源基线；模拟器还要求固件与操作系统提供可用的硬件虚拟化。不要把文档里的最低值直接当团队采购标准：打开多模块工程、运行 Gradle daemon、保留索引并同时启动多个 AVD 时，峰值内存和磁盘写入才是容量依据。
macOS 应按 Intel 与 Apple Silicon 选择匹配安装包和 system image；Linux 官方桌面 IDE/Emulator 路径以受支持的 64 位环境为主。资源不足时，真实设备通常比勉强运行无加速模拟器更可靠；云端 Device Streaming 适合补设备覆盖，但不能替代本地离线能力和发布前真实设备验证。
企业环境还要确认：能否访问 Google SDK 仓库、是否有 HTTPS 代理和根证书、SDK 包能否离线归档、USB 设备是否被终端安全策略阻断、无线调试是否允许进入当前网络。把 Studio 单独装成功，并不能证明 SDK 下载、Gradle 依赖解析和设备调试三条网络链路都已打通。
安装前先验证虚拟化
Windows 可以在任务管理器 CPU 页面查看“虚拟化”，也可以使用系统信息确认 Hyper-V 条件。Linux 可检查 CPU flag，macOS 则按硬件与系统能力确认 hypervisor。安装 Emulator 后，最直接的验证入口是：
emulator -accel-check预期结果是当前平台的 hypervisor 可用。若提示 VT-x/AMD-V 未启用，先进入 BIOS/UEFI；若提示另一个虚拟化产品冲突，要根据操作系统当前官方加速方案调整，不要同时叠加互斥 hypervisor。企业 VDI、嵌套虚拟化和受管终端可能从平台层禁止加速，此时应转向物理设备或远程设备，而不是继续调 AVD 内存。
安装 Android Studio 与确认许可边界
从 Android Developers 下载与操作系统和 CPU 匹配的正式安装包。Windows 推荐 EXE，也提供 ZIP；macOS 使用对应架构包；Linux 解压后从 bin/studio 启动。首次 Setup Wizard 安装推荐 SDK 组件，并让用户逐项接受所需许可。
基础 IDE 使用不要求先登录 Google 账号，但 Gemini、Firebase、Device Streaming 等在线服务可能要求账号并受各自条款、组织策略和支持窗口约束。Android Studio 与 SDK Manager 中的 package 在安装时需要接受相应条款；开源组件、SDK package、Google APIs/Play system image 也不是一个统一许可证对象。企业镜像和离线分发必须保留 package 元数据、NOTICE 和许可接受流程。
安装后先记录 Help -> About 中的 Android Studio build、Runtime version 与 VM。不要先改 STUDIO_JDK：官方建议使用随 Studio 分发并经过测试的 JetBrains Runtime（JBR）启动 IDE。
SDK 目录与 package 必须可重建
SDK Manager 管理的是 package，不是一个不可解释的大目录。最小 Android 应用通常至少需要：
platform-tools，其中包含 adb。目标 API 的 platforms;android-<api>。与项目兼容的 build-tools;<version>。
使用模拟器时的 emulator 与一套 system image。只有原生代码需要时才安装 NDK/CMake，并锁定版本。
在 IDE 中通过 Tools -> SDK Manager 安装最直观。团队和 CI 更适合使用 Command-Line Tools 中的 sdkmanager。下面用占位 API 演示命令形状；实际值必须从仓库的 compileSdk、目标 AGP release notes 和团队 package 清单读取：
sdkmanager --list
sdkmanager "platform-tools" "platforms;android-<api>" "build-tools;<version>" "emulator"
sdkmanager --licenses--list 应显示 installed/available package；安装命令成功后，对应 package 出现在 SDK 目录；--licenses 会交互接受尚未接受的许可。脚本应锁定 Command-Line Tools 与 package 版本，不要在 CI 无条件执行 sdkmanager --update，否则同一 commit 的工具链会随时间变化。
SDK 路径属于机器配置。local.properties 中常见的 sdk.dir 不应被当成跨机器团队配置，更不能把本机用户名路径复制给所有人。团队应提交“需要哪些 package”的脚本或清单，让每台机器在自己的 SDK 根解析。
创建 AVD：选择代表性设备，不是越多越好
AVD 由硬件 profile、system image、存储、skin 与设备属性组成。Device Manager通过 Tools -> Device Manager -> Create Virtual Device 选择设备外形和 API。最小开发集通常包括一个目标 API 的主力 AVD，再按业务风险补低版本、平板、折叠屏或其他形态。
system image 要按用途选择：带 Play Store 标识的 image 更接近有 Google Play 的用户设备，并使用 release key，不能通过 adb root 获取高权限；需要底层排障时可使用不含 Google 服务的 AOSP image，但它不能代表 Play 服务行为。测试 Google Maps、Firebase 或 Play 依赖时，不能拿纯 AOSP image 得出兼容结论。
命令行环境可以先安装 image，再用 avdmanager 创建：
sdkmanager "system-images;android-<api>;google_apis;<abi>"
avdmanager create avd -n sample_api_<api> -k "system-images;android-<api>;google_apis;<abi>"
emulator -avd sample_api_<api>Apple Silicon 应选择匹配的 arm64-v8a image；具体 package 名以 sdkmanager --list 为准。预期是 Emulator 启动到 Android 桌面，并在 adb devices 中出现 emulator-<port> 且状态为 device。
AVD 的 userdata 会保留安装应用、账号和设置。测试结果异常时，可先在 Device Manager 执行 Cold Boot；需要回到干净状态再执行 Wipe Data。不要把“每次失败都删 AVD”写成日常 SOP，因为这会掩盖 snapshot、存储、应用升级或数据迁移类缺陷。
ADB：先证明设备身份，再运行应用
ADB 由 client、主机上的 server 和设备上的 daemon 组成。先让 SDK 的 platform-tools 进入可控 PATH，然后执行：
adb version
adb devices -l预期是版本来自当前 SDK 根，设备列表中目标状态为 device。常见状态含义不同：unauthorized 表示设备尚未接受当前主机 RSA key；offline 表示传输或 daemon 状态异常；列表为空则继续查 USB 驱动、线缆、端口、Linux udev/plugdev 或无线网络。
物理设备需要启用 Developer options 和 USB debugging。Windows 某些厂商设备需要 OEM USB driver；Ubuntu 用户通常需要 plugdev 组和覆盖设备的 udev rules。首次连接时在已解锁设备上核对并接受 RSA 指纹，不要在公共调试机勾选永久信任。
Android 11 及以上可以使用 Wireless debugging，通过 Android Studio 的 Pair Devices Using Wi-Fi 或配对码建立信任。它适合摆脱 USB 线缆，不应在不可信 Wi-Fi 中长期启用。任务结束后从设备的 Paired devices 中 Forget 工作站，或撤销 USB debugging authorizations。
出现设备状态异常时可以有限度重启 ADB server：
adb kill-server
adb start-server
adb devices -l如果重启后仍为空，原因通常不在 ADB server 本身。继续换线、检查 USB mode、驱动、udev、企业终端管控和设备端授权，并用另一台设备做交叉验证。
三类 JDK 必须分开理解
IDE JDK：启动 Android Studio
Android Studio 默认使用内置 JBR。它决定 IDE UI、索引和插件运行，不直接决定 Android 应用能用哪些 Java API。Android 构建的 JDK 说明建议保留经过 Studio 测试的 JBR；只有在支持要求明确时才设置 STUDIO_JDK，并记录回退方式。
Gradle JDK：运行 Gradle daemon
从 Android Studio 点击 Sync/Build 时，Gradle 使用 IDE 设置中的 Gradle JDK；从终端运行 Wrapper 时，通常由 JAVA_HOME 或 PATH 中的 Java 决定。两者不同会产生“IDE 能构建、CI 失败”或反向现象。
项目可在 Settings -> Build, Execution, Deployment -> Build Tools -> Gradle 查看 Gradle JDK。官方在多数项目中推荐 GRADLE_LOCAL_JAVA_HOME；它通过项目 .gradle/config.properties 中的 java.home 解析本地 JDK。较新的项目还可能使用 Gradle Daemon JVM criteria。升级时应从 ./gradlew --version 和仓库配置确认实际 daemon JVM，不能假设旧 .idea/gradle.xml 永远是唯一来源。
先比较 IDE 与终端：
./gradlew --version预期输出包含 Gradle、Launcher JVM 与 Daemon JVM。Windows 使用 gradlew.bat --version。团队应在本地与 CI 留存这一段，而不是只记录 java -version。
Java toolchain：编译源码和运行 Java 工具
Java toolchain 决定编译 Java 源码所用的 JDK，也可用于 Javadoc 和单元测试。它与运行 Gradle 的 JDK 职责不同。官方建议显式声明 toolchain，以降低开发机与 CI 的编译差异：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
android {
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
}compileSdk 仍会限制 Android 可用 API；toolchain 版本高不代表旧 Android 系统拥有同样 Java API。Kotlin 的 JVM target 还需按当前 Kotlin 插件口径配置。架构评审时要分别写清“谁启动 Studio、谁运行 Gradle、谁编译源码、应用最低 API 是多少”。
用兼容矩阵管理 Studio、AGP、Gradle 与 JDK
不要把 Android Studio、AGP、Gradle 和 JDK 一起点击升级。Studio 与 AGP 兼容表使用时间窗口描述 IDE 能打开哪些 AGP；目标 AGP 的 release notes 再规定最低 Gradle、JDK、Build Tools 与可支持的 API。前一张表解决“IDE 是否接受项目”，后一张表解决“构建工具链能否运行”，不能把一个区间误读成任意组合都兼容。
正确顺序是：
从仓库读取 AGP 版本和 gradle-wrapper.properties。在官方 Studio/AGP 表中确认 IDE 窗口。在目标 AGP release notes 中确认所需 Gradle、JDK、SDK Build Tools 与最大 API。
在独立分支执行 AGP Upgrade Assistant 或手工迁移。先跑 CLI clean build 与测试，再打开新 Studio Sync。对构建插件、Variant API、DSL 和自研 Gradle plugin 做弃用扫描。
AGP API 路线图已经把惰性 Variant API、Provider 和 artifact model 作为升级方向。依赖旧 Variant API、已弃用 Transform API 或 AGP 内部类的自研插件，应在升级分支先运行弃用扫描与 Upgrade Assistant；“旧 Studio 还能编译”不能证明下一条稳定发布线仍会保留内部实现。
导入、Sync 与最小构建验证
先在终端从仓库根执行：
./gradlew --version
./gradlew tasks
./gradlew assembleDebug预期依次是 JDK/Gradle 身份可解释、项目 task 图可读取、debug APK/AAB 对应任务成功。然后在 Android Studio 选择包含 settings.gradle(.kts) 的根目录，不要只打开 app/ module。
Gradle Sync 会启动或复用 Gradle daemon，解析 settings、plugin management、版本目录、仓库、build logic、AGP model、SDK 和 variant，再把工具模型交给 IDE。IDE 将这个模型用于代码分析、资源索引、variant 选择和运行配置；真正的 APK/AAB 仍由 Gradle task 图产生。Sync 成功后仍要执行 assembleDebug 或项目约定的测试；构建成功但 Sync 失败，则检查 IDE JDK、Studio/AGP 窗口和 IDE 代理；Sync 成功但构建失败，则看具体 task、编译器和依赖错误。
可以用一个受控反例验证这条边界：先记录 ./gradlew --version，再让 Android Studio 的 Gradle JDK 临时指向不满足目标 AGP 的 JDK，执行 Sync 并保存错误中报告的 Java 路径；随后恢复团队 JDK、执行 ./gradlew --stop，重跑 Wrapper 与 Sync。预期是错误路径消失、daemon JVM 与基线一致，Git diff 只包含事先批准的配置变化。不要用修改 sourceCompatibility 伪装修复，因为它控制源码编译级别，不控制运行 AGP 的 JVM。
最小项目闭环是：选择 debug variant，选择一个 AVD 或受控物理设备，执行 Run，确认应用安装并进入目标 Activity；随后在可控代码行设置断点，用 Debug 触发一次交互。最后用命令交叉验证：
adb devices -l
adb shell pm list packages | grep sample
adb logcat -d -t 200Windows 没有 grep 时用 findstr sample。包名必须替换为无敏感的测试 application ID。预期是设备在线、测试包已安装、logcat 出现当前进程的启动证据且没有崩溃栈。
真实项目接入与日常提效
真实仓库应把版本权威放在代码中：Gradle Wrapper、AGP/Kotlin/plugin 版本、Version Catalog、compileSdk/minSdk/targetSdk、toolchain 与测试任务都进入评审。机器级 SDK 路径、代理凭证、签名密钥路径和设备序列号不提交。
日常效率来自减少隐式状态：
用 Gradle tool window 调用仓库已有 task，不在 IDE 里复制第二套构建逻辑。为常用 variant 建立无敏感 Run Configuration，环境差异通过受控本地配置注入。用 Device Manager 给 AVD 采用可读命名，例如 API、image 类型和形态，不使用个人姓名。
先用 adb devices -l 确认目标，再执行安装、清数据或 shell 命令；多设备时显式使用 -s <serial>。性能问题先区分 Studio heap、Gradle daemon、Kotlin daemon 和 Emulator 内存，不能只把 IDE heap 一路调大。
更新通道与回滚
Android Studio 更新说明区分 Stable、RC 和 Canary。Stable 是正式稳定版本；RC 用于发布前反馈；Canary 更新频繁，不适合作为团队唯一开发基线。需要试用预览版时应与 Stable 并行安装，使用独立配置/缓存边界，并在副本分支验证，不能让 Preview 自动迁移唯一工作环境。
手工安装由 Studio 检查更新；通过 JetBrains Toolbox 安装时由 Toolbox 管理更新，并支持 Stable、RC、Canary 并行与版本回退。无论入口如何，团队升级单都要记录 Studio build、AGP、Gradle、JDK、SDK package、Emulator 与 system image，不能只写“升级 Android Studio”。
回滚 IDE 不一定能回滚项目。若 Upgrade Assistant 已修改 build scripts，应通过 Git 回退项目变更；若新 AGP 已改变缓存或生成物，回退后先停止 daemon 并重建；若 AVD system image 已升级，保留旧 AVD 或可重新创建的 image 清单。IDE、项目与设备数据要分别制定回滚。
清理与重置：每一层单独处理
停止 Gradle daemon：
./gradlew --stop清理项目构建产物优先使用项目任务：
./gradlew cleanclean 不会清全局 Gradle cache，也不会删除 SDK、AVD 或 IDE 索引。全局缓存删除会导致大量重下载，在企业代理/离线环境可能让所有项目同时不可构建，因此必须先证明缓存损坏并保留回退。
SDK package 用 SDK Manager 或 sdkmanager --uninstall "package-id" 移除；AVD 用 Device Manager 删除，或使用：
avdmanager delete avd -n sample_api_36卸载测试应用可执行：
adb uninstall com.example.sample执行前显式确认 serial 和 application ID。删除 AVD 会丢失其 userdata；Wipe Data 也会清账号与安装应用。Android Studio 大版本首次启动可能提示删除未使用的旧配置、索引和日志目录，应先核对目录对应版本、大小和最后修改时间，再清理。
故障排查：现象、判断、原因、修复、再验证
Emulator 很慢或直接提示 acceleration unavailable
先运行 emulator -accel-check。若硬件能力不可用，检查 BIOS/UEFI、宿主 hypervisor 和嵌套虚拟化；若能力可用但仍慢，再看 AVD 架构是否匹配主机、GPU driver、内存和磁盘。修复后冷启动 AVD，并用 adb devices -l 验证它真正进入 device 状态。
adb devices 显示 unauthorized、offline 或空列表
unauthorized 要在设备端核对 RSA 指纹；offline 可重启 ADB server、重插设备并检查传输；空列表继续排查线缆、USB mode、OEM driver、udev/plugdev、无线网络和终端安全策略。再验证必须看到目标 serial 的 device，不能只看 Android Studio 设备下拉框出现名称。
Sync 报 “AGP requires Java …”
先看 ./gradlew --version 的 Launcher/Daemon JVM，再看 Android Studio Gradle JDK。根因通常是终端 JAVA_HOME 与 IDE Gradle JDK 不一致，或 AGP 已提高最低 JDK。统一到兼容 JDK后停止旧 daemon，重新运行 ./gradlew --version 和 Sync；不要通过降低 sourceCompatibility 解决运行 Gradle 的 JDK 不兼容。
IDE 能构建，终端或 CI 失败
比较 Gradle Wrapper、Gradle JDK、代理、SDK 根、已接受许可和 package 列表。把缺失项写入 bootstrap 脚本或 CI image，再从干净环境执行 tasks、assembleDebug 和测试。复制个人 .gradle 或整个 SDK 目录只能制造新的不可追踪状态。
下载依赖或 SDK package 失败
先区分 Gradle 仓库与 Android SDK 仓库。前者看 Gradle proxy、repository 与证书；后者看 Studio/SDK Manager proxy、企业 CA 和允许域名。证书错误应修 trust chain，不使用 --no_https 绕过；离线环境应由团队制品入口提供经校验的 SDK package 和 Maven artifact。
构建成功但 Run 安装失败
从 Run 输出和 adb 错误判断是设备离线、空间不足、签名不一致、version downgrade、minSdk 高于设备 API，还是工作 profile/企业策略阻断。清数据或卸载前确认不会破坏测试证据；修复后重新安装，并从设备 package 与 logcat 两侧验证。
架构选型与能力边界
Emulator 适合稳定复现 API、分辨率、locale、网络和快照场景；物理设备覆盖真实厂商系统、传感器、功耗、相机、蓝牙和 USB；Device Streaming/Test Lab 适合扩大设备矩阵。成熟团队通常组合使用，而不是选一个替代全部。
Android Studio 是开发入口，不应成为构建唯一入口。CI 必须从 Wrapper 和声明式 SDK/JDK 基线完成构建；开发机通过同一命令复现。Run Configuration 可以提高交互效率，但不能承载只有 IDE 才知道的关键参数。
权限、账号、凭证与敏感信息
ADB 授权等于允许开发机对解锁确认过的设备执行安装、shell、端口转发和数据调试。共享测试机应定期撤销授权，设备 serial 与日志按资产信息处理。无线调试只在受信网络临时启用。
Android Studio 插件运行在拥有源码、索引、构建输出和网络访问能力的 IDE 进程中，不能因为能从 Marketplace 搜到就自动进入团队基线。JetBrains Marketplace 的插件安全说明表明上架插件会经过自动检查和人工审核，但审核不能替代组织自己的来源、vendor、兼容版本、许可证、数据外发和更新变更评估。团队应维护允许清单，在隔离项目验证新版本，保留禁用或回退路径；来源不明的本地 ZIP 插件不得用“临时排障”绕过准入。
重点扫描 local.properties、gradle.properties、Run Configuration、签名配置、Firebase/云服务配置、logcat 和截图。不要提交 keystore、store password、key password、OAuth client secret、服务账号 JSON、代理凭证或真实生产 endpoint。google-services.json 中并非每个字段都是秘密，但仍要按项目和环境治理，不能据此放松对真正服务端密钥的保护。
Google 账号只用于确有需要的在线服务，团队设备不共享个人账号。企业应明确哪些开发者可以使用 Gemini、Device Streaming、Firebase 和预览服务，以及源码/日志能否发送到外部服务。
团队治理与长期维护
团队基线至少记录：Android Studio channel/build、AGP、Gradle Wrapper、Gradle Daemon JVM criteria 或 Gradle JDK、Java toolchain、compile/min/target SDK、必要 SDK package、主力 AVD、真实设备矩阵和许可接受方式。每项都有 owner 和升级窗口。
升级先在样板仓库与独立 Studio 安装中执行，依次验证 Sync、CLI build、单测、instrumented test、一个 AVD、至少一台受控真实设备和回滚。CI 应输出 ./gradlew --version 与关键 SDK package 身份，使“本机可以”能被比较，而不是争论。
容量治理要观察 Studio/Gradle/Emulator 总内存、多个 daemon、AVD userdata、system image、SDK/NDK 与 Gradle cache 的磁盘增长。清理脚本只能删除明确命名且由当前项目拥有的对象，禁止把全局 SDK、全部 AVD 或整个 Gradle cache 做成一键定期任务。
团队自检
硬件、内存、磁盘、CPU 架构和虚拟化满足本地方案，emulator -accel-check 有执行证据。SDK package 有版本清单、许可记录、代理/离线入口和清理边界。IDE JBR、Gradle JVM 与 Java toolchain 已分别确认，./gradlew --version 与 CI 一致。
Studio/AGP/Gradle/JDK 按官方兼容矩阵升级，Preview 与 Stable 隔离。AVD 或受控设备完成构建、安装、运行、断点和 logcat 验证。ADB 授权、签名材料、账号、日志和 Run Configuration 不泄露敏感信息。
IDE、项目、SDK、AVD 与缓存都有独立回滚和清理方案。