local.properties文件缺失或路径错误是最常见原因，需手动创建并正确配置sdk.dir路径（推荐正斜杠），同时确保ANDROID_HOME等环境变量不冲突，且该文件不可提交至Git。
local.properties 文件缺失或路径写错
这是最常见原因：项目根目录下没有 local.properties，或者文件里写的 sdk.dir 路径根本不存在、拼错了、多了一个空格，或者用了反斜杠没转义（Windows 下写成 sdk.dir=C:Users
ameAppDataLocalAndroidSdk 会报错，必须写成 sdk.dir=C:\Users\name\AppData\Local\Android\Sdk 或用正斜杠 sdk.dir=C:/Users/name/AppData/Local/Android/Sdk）。
实操建议：
- 先确认你本地 SDK 真实路径——打开 Android Studio → Preferences（macOS）或 Settings（Windows/Linux）→ Appearance & Behavior → System Settings → Android SDK，看右上角“Android SDK Location”显示的路径
- 在项目根目录手动创建
local.properties文件（不是app/local.properties，也不是gradle.properties） - 写入一行：
sdk.dir=/your/actual/sdk/path（macOS/Linux）或sdk.dir=C:/Users/xxx/AppData/Local/Android/Sdk（Windows，推荐正斜杠） - 保存后执行
./gradlew clean或在 Android Studio 里点击 “Sync Project with Gradle Files”
ANDROID_HOME 或 ANDROID_SDK_ROOT 环境变量干扰
Gradle Android 插件读取 SDK 路径的优先级是：local.properties > ANDROID_HOME > ANDROID_SDK_ROOT。如果你设了环境变量但路径不对，它会直接忽略 local.properties 里的配置，然后报错。
实操建议：
- 终端运行
echo $ANDROID_HOME（macOS/Linux）或echo %ANDROID_HOME%（Windows），检查是否意外设置了旧路径 - 如果不需要环境变量兜底（比如只在本机开发），直接注释掉
~/.zshrc、~/.bash_profile或系统环境变量里的相关 export 行 - 如果要用环境变量（如 CI 场景），确保
$ANDROID_HOME/platforms/android-34这类目录真实存在；否则 Gradle 仍会失败，不只是“找不到 SDK”，而是“找不到对应 platform”
Android Studio 自动写入路径失败或路径被覆盖
新版 Android Studio（2023.2+）默认把 SDK 装到 ~/Library/Android/sdk（macOS）或 %LOCALAPPDATA%AndroidSdk（Windows），但老项目 local.properties 可能还写着 /usr/local/android-sdk 或 /opt/android-sdk。更隐蔽的是：某些插件或脚本（比如用 sdkmanager 升级后）可能偷偷重写 local.properties，把路径改成它认为“正确”的位置，结果反而指向一个空目录。
实操建议：
- 不要依赖 Android Studio 自动创建
local.properties——它有时会写错，尤其在多 SDK 共存时 - 每次换机器、重装 AS、或拉别人项目前，先删掉旧的
local.properties，再手动建一个，内容只有一行sdk.dir=+ 你当前确认有效的路径 - 用
ls -la $sdk_path/platforms/（macOS/Linux）或dir %sdk_path%platforms（Windows）验证android-34、android-33等目标平台是否存在；缺失的话，得进 SDK Manager 补装
Git 提交了 local.properties 导致路径冲突
local.properties 是典型的本地配置文件，绝对不该进 Git。但很多人 clone 项目后发现已有这个文件，就直接用了，结果里面写的路径是原作者电脑上的，跟你完全不匹配。
实操建议：
- 检查项目根目录是否存在
local.properties，如果存在，先cat local.properties（macOS/Linux）或type local.properties（Windows）看内容 - 如果路径明显不属于你本机（比如含
/home/john/...或C:UsersAlice...），立刻删掉它，再按第一部分重新创建 - 确认项目根目录下的
.gitignore是否包含local.properties；如果没有，追加一行并提交（但别把已提交过的该文件再推上去） - CI 构建时更推荐用
ANDROID_SDK_ROOT+ 镜像缓存，而不是靠local.properties
真正容易被忽略的是：即使 sdk.dir 指向了正确目录，如果那个目录下缺了 platform-tools 或 build-tools/34.0.0，Gradle 同样会卡在“SDK location not found”这个错误提示里——它没说清楚到底是“路径不存在”，还是“路径下关键组件缺失”。验证时务必 cd 进去，手动 ls 一眼。
