构建期失败需四步定位：一查gradle与jdk版本兼容性（如agp 8.4需gradle≥8.6且jdk=17）；二验settings.gradle中include(":app")语法正确；三清缓存并强制重同步（invalidate caches或命令行清理）；四通过布局编辑器提示验证基础构建是否通过。
Android Studio运行项目失败时，项目根本无法启动或安装到设备，控制台报错集中在Gradle构建阶段、资源编译、依赖解析或模块识别等环节，必须逐层定位才能恢复可运行状态。
确认是否为构建期失败
点击菜单栏 Build → Make Project，观察底部 Build 窗口输出内容。若出现 Failed、error: 或红色堆栈（如 MultipleCompilationErrorsException、Could not resolve），说明是构建期失败；若只显示 Installation did not succeed 且无红色错误，则属于运行期问题，跳过本节直接查设备连接与Manifest配置。
这一步操作起来很简单，直接看 Build 窗口最顶部那行字就行——它不会骗人。
检查 Gradle 与 JDK 版本兼容性
Gradle 和 JDK 版本不匹配会直接导致 sync 失败，且错误提示常被淹没在冗长日志中，极易误判为网络或依赖问题。
第一步：打开项目根目录下的 gradle/wrapper/gradle-wrapper.properties，找到 distributionUrl 行，例如：distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
第二步：打开项目级 build.gradle.kts（或 build.gradle），查看 com.android.tools.build:gradle 版本，例如：id("com.android.application") version "8.4.0" apply false
第三步：对照官方映射表验证组合是否合法——AGP 8.4 要求 Gradle ≥ 8.6 且 JDK = 17。若你用的是 Android Studio 内置 JDK（jbr-21），必须手动切换回 jbr-17：File → Project Structure → SDK Location → JDK location → 选择 Android Studio.app/Contents/jbr/Contents/Home 下带 17 的子目录。
⚠️ 注意：JDK 21 与 AGP 8.4 不兼容，强行使用会导致 NoClassDefFoundError: java/lang/Thread$Builder 类似报错，且不会明确提示 JDK 版本问题。
修复 settings.gradle 中的模块声明
当控制台报 Project 'app' not found in root project，本质是 Android Studio 根本没识别出 app 模块，后续所有构建动作都会失效。
远程控制 Android 设备，支持截图、自动化操作手机 App 等功能。本应用使用 uiautomator2 作为底层框架，通过 ADB 连接设备，用户无需 Root（1）查看手机屏幕；（2）自动化操作手机 App；（3）远程安装/卸载应用……
打开项目根目录下的 settings.gradle（或 settings.gradle.kts），确认内容包含且仅包含以下有效声明：
include(":app")
如果文件里写的是 include ':app'（无括号、无冒号）或 include("app")（漏掉冒号），都会导致模块注册失败。KTS 文件还必须确保没有语法错误——比如末尾多了一个逗号、字符串未闭合引号。
若项目含多个模块（如 :core、:feature），每个都必须显式 include，且路径与实际文件夹名完全一致（区分大小写、不含空格、不带 .gradle 后缀）。
清理缓存并强制重同步
方法一：菜单操作
File → Invalidate Caches and Restart → Select “Invalidate and Restart”
方法二：命令行强制清理（更彻底）
关闭 Android Studio → 终端进入项目根目录 → 执行：./gradlew clean && rm -rf .gradle build/（macOS/Linux）gradlew clean && rd /s /q .gradle build（Windows CMD）
重启后不要立刻 Run，先点右上角 Sync Now 按钮，等待 Gradle 完整下载依赖、解析 DSL、生成中间文件。这一步耗时较长，但跳过会导致后续所有操作基于损坏缓存，反复失败。
快速验证布局编辑器能否启用
打开任意 res/layout/*.xml 文件，若编辑器左下角显示 “Design editor is unavailable until after a successful project sync”，说明项目尚未通过基础构建校验——此时无需调试 UI，优先回到前四步排查。
只有当该提示消失、Design 标签可点击、预览窗能渲染出控件时，才代表项目已通过资源编译、AAPT2 链接、Manifest 合并等关键关卡，可进入真机部署阶段。
