Gradle同步成功不等于项目能编译通过，因同步仅验证配置与依赖可解析，而编译失败多源于模块配置错误、资源引用缺失、JDK版本不兼容或XML语法违规，需重点检查settings.gradle.kts模块声明、资源路径与命名规范、JDK与AGP匹配性及build.gradle.kts中namespace等强制配置。
Gradle 同步成功 ≠ 项目能编译通过。同步只是验证了构建配置和依赖可解析，而编译失败说明代码、资源或构建逻辑在实际执行阶段出了问题。常见原因集中在模块配置、资源引用、JDK 兼容性、XML 语法这四类，且错误日志往往藏在 Build 窗口底部而非弹窗中。
检查 settings.gradle.kts 中的模块声明是否合法
同步成功但 Build → Make Project 报 Project 'app' not found in root project，基本是模块未被正确注册。
-
include(":app")是唯一被 AGP 8.2+ 正确识别的写法；include("app")或include ':app'都会静默失效 - 若项目含多个模块（如
:feature:login），每个都必须显式include，不能只写include(":app")就以为自动包含子目录 - 文件编码必须为 UTF-8，BOM 头会导致解析失败（尤其 Windows 下用记事本保存后）
验证 res/layout/ 和资源引用是否合规
布局编辑器显示 “Design editor is unavailable until after a successful project sync” 是典型假象——它其实是在说“编译失败，我连 XML 解析都做不了”。
- 所有 XML 文件名必须全小写、仅含字母/数字/下划线，
main_activity.xml✅，MainActivity.xml❌，activity-1.xml❌ -
android:src="@drawable/ic_launcher"这类引用，要求ic_launcher.png确实存在于res/drawable/或其变体目录（如drawable-hdpi），缺一个就会卡在processDebugResources - 如果用了
@string/app_name，但strings.xml里没定义该 key，编译会直接中断，不会提示具体哪行 XML 错了
确认 JDK 版本与 AGP/Gradle 实际兼容
即使同步成功，JDK 不匹配仍会在编译阶段抛出 NoClassDefFoundError 或 Unsupported class file major version。
- AGP 8.4 要求 JDK 17，但 Android Studio 内置的
jbr-21默认启用——必须手动切回jbr-17：File → Project Structure → SDK Location → JDK location → 指向Android Studio.app/Contents/jbr/Contents/Home下带17的路径 - 不要依赖 IDE 自动选 JDK；检查
gradle.properties是否有org.gradle.java.home指向错误 JDK - 命令行执行
./gradlew --version输出的JVM版本，必须与 IDE 设置一致
排查 build.gradle.kts 中的 DSL 语法错误
同步成功只校验脚本结构，不执行所有闭包逻辑；某些 DSL 方法在编译期才触发，比如 android.namespace 在 AGP 8.2+ 是强制项，漏写会导致 Could not read entry ':app:processDebugManifest'。
-
android { namespace = "com.example.myapp" }必须存在，且值需与package声明完全一致 - 插件重复应用：
plugins { id("com.android.application") }和apply(plugin = "com.android.application")不能共存 - 使用
implementation时误写成implement或implemenation，这类拼写错误同步不报错，但编译时找不到依赖类
最容易被忽略的是：同步成功后，Build 窗口里可能仍有黄色警告（如 Configuration on demand is an incubating feature），但它不影响编译；而真正致命的错误往往混在几十行日志中间，被折叠或滚动过去。务必点开 Build 窗口右上角的 Toggle view 图标，切换到 Build 标签页，从最底部往上翻，找第一个红色 error: 行——那才是真正的断点。
