local.properties 文件需手动创建并配置 sdk.dir 路径，路径须正确、无中文空格括号、末尾不加斜杠、Windows 用正斜杠或双反斜杠；它不提交至 Git，由 AGP 解析且优先级高于 ANDROID_HOME。
local.properties 文件不存在时怎么补上
Gradle 同步报错 SDK location not found，八成是因为项目根目录下压根没这个文件。它不会自动创建，除非你用 Android Studio 新建项目或手动触发 SDK 路径配置（比如在 Project Structure → SDK Location 里点一下“Apply”）。
手动创建很简单：touch local.properties（macOS/Linux）或新建文本文档改名为 local.properties（Windows），然后写入：
sdk.dir=/path/to/your/android-sdk
注意几点：
-
sdk.dir是唯一必需项；ndk.dir只有你真用 NDK 才加 - 路径不能带中文、空格、括号——哪怕只是路径里有个
(x64)都可能让 Gradle 解析失败 - Windows 上必须用正斜杠
/或双反斜杠\，单反斜杠是非法转义字符，会直接导致读取失败 - 路径末尾不要加斜杠，
sdk.dir=/Users/me/Library/Android/sdk/中的结尾/会导致部分 Gradle 版本识别为无效路径
sdk.dir 路径写错了会有什么表现
最常见的是同步卡在 “Resolving dependencies” 或直接抛 Failed to find Build Tools revision。但真正根源往往藏在日志深处：打开 Build Output 面板，搜 sdk.dir，你会看到类似这样的行：
Reading local.properties from /path/to/project/local.properties sdk.dir value: 'C:Users ameAppDataLocalAndroidSdk' SDK dir does not exist: C:Users ameAppDataLocalAndroidSdk
关键线索是最后一句——Gradle 真的去文件系统里查了，但路径不存在。这时要检查：
- 路径是否拼错（比如
Sdk写成SDK，macOS 对大小写不敏感，Windows 和 CI 机器可能敏感） - 是否复制了 Android Studio 设置界面里显示的“灰色提示路径”，那个路径有时带未展开的环境变量如
%LOCALAPPDATA%，Gradle 不认这个 - 是否用了符号链接或 OneDrive/Google Drive 同步目录——某些 Gradle 插件版本无法正确解析挂载路径
为什么不能把 local.properties 提交到 Git
因为它的内容是绝对路径，而每个开发者的 SDK 安装位置几乎必然不同。一旦有人把他的 sdk.dir=/home/alice/Android/Sdk 提交上去，同事 git pull 后同步就会立刻失败。
验证是否已忽略：
- 运行
git check-ignore -v local.properties，如果返回规则（比如.gitignore:23:/local.properties），说明已生效 - 如果没反应，说明没忽略，立刻加一行
/local.properties到项目根目录的.gitignore里 - 如果已经误提交过，得用
git rm --cached local.properties把它从索引中踢出，再 commit
团队里最稳妥的做法是：文档里写清楚“首次拉代码后需自行创建 local.properties”，而不是靠脚本自动生成——后者容易绕过 .gitignore 或写错权限。
构建时 Gradle 到底怎么读 local.properties
Gradle 并不直接加载这个文件，而是 Android Gradle Plugin（AGP）在初始化阶段主动读取。它只认项目根目录下的 local.properties，不会向上查找父目录，也不会合并多个同名文件。
读取逻辑很朴素：
- 先尝试打开
project.rootDir/file("local.properties") - 逐行解析，跳过以
#或!开头的注释行 - 对每行执行
String.split("=", 2)，取第一个=左边为 key，右边为 value（value 前后 trim 空格） - 只认
sdk.dir和ndk.dir这两个 key，其余全丢弃
所以别指望加 foo.bar=baz 来传参，也别用冒号 : 或等号嵌套——它就是个极简 key-value 解析器，多一个字符都可能让整行失效。
真正容易被忽略的是：如果你在 CI 环境里用命令行构建（./gradlew assembleDebug），而机器上没配 ANDROID_HOME，又没有 local.properties，那构建一定失败。这时候要么在 CI 脚本里提前生成该文件，要么统一用环境变量兜底，但别两者混用——local.properties 优先级高于 ANDROID_HOME，一旦文件存在，环境变量就彻底被忽略。
