原生移动开发 / 知识点
Android 项目目录与文件用途速查
界面与资源文件
为夜间模式提供 values 资源覆盖,系统进入 Dark Mode 后可自动选择;主题或颜色只在深色模式异常时应检查这里。
values-night 目录
res/values-night/ 是带 night 配置限定符的 values 资源目录。设备或应用处于夜间模式时,Android 资源系统会优先从这里选择匹配资源;没有对应覆盖项时,仍会回退到普通 res/values/,因此不需要复制全部资源。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
values/ 与 values-night/ 存在同名资源 |
日间和夜间使用不同值 | 对照两处资源值是否符合设计要求 |
只有 values/ 中定义资源 |
夜间没有专门覆盖 | 确认默认值在深色背景下是否仍可用 |
| 只在深色模式出现颜色或主题异常 | 夜间资源可能覆盖错误 | 优先检查 values-night/ 中的同名项 |
修改普通 values/ 后深色模式仍不变 |
更具体的 night 资源正在生效 |
搜索 values-night/ 中是否存在同名资源 |
Android 按资源类型和名称进行匹配,而不是按文件名覆盖整个文件。例如 values/colors.xml 和 values-night/colors.xml 可以只共享其中几个颜色名称。
主示例
普通模式先提供默认颜色:
<!-- res/values/colors.xml -->
<resources>
<color name="screen_background">#FFFFFF</color>
<color name="primary_text">#202124</color>
</resources>夜间目录只覆盖需要变化的值:
<!-- res/values-night/colors.xml -->
<resources>
<color name="screen_background">#121212</color>
<color name="primary_text">#F1F3F4</color>
</resources>布局或主题继续引用相同资源名,例如 @color/screen_background。进入夜间模式后无需修改调用代码,资源系统会选择 values-night 中更匹配的值。
预期结果:普通模式使用浅色背景和深色文字;夜间模式使用深色背景和浅色文字。实际显示还会受到主题、动态颜色以及组件自身样式影响。
出现条件与范围
night 属于 Android 的 uiMode 配置限定符。系统深色模式通常会改变该配置;使用 AppCompat 等方案时,应用也可以主动设置自身的夜间模式,因此不能只根据系统设置推断最终资源选择结果。
目录中可以放置颜色、样式、尺寸等 values 类型 XML,但只有需要随夜间模式变化的资源才应覆盖。不要为了保持两个目录结构一致而复制所有默认值,否则容易造成后续修改只更新一处。
排查顺序
深色模式异常时,先确认问题资源的实际名称,再搜索 values-night/ 是否存在同名定义;随后检查主题属性是否间接引用了另一项资源。若删除夜间覆盖后表现恢复正常,通常说明问题来自更具体的 night 资源,而不是基础 values/。
保存网络安全、备份、FileProvider 路径等结构化 XML 配置;具体文件用途取决于 Manifest、组件或系统 API 的引用方式。
xml 目录
res/xml/ 用于保存需要由 Android 框架、组件或应用代码按 XML 结构读取的配置资源。文件会参与资源编译,并以 R.xml.<name> 或 @xml/<name> 的形式被引用;仅把文件放进目录并不会自动启用任何配置。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
Manifest 中出现 @xml/<name> |
某个系统或组件配置引用了该文件 | 打开对应 XML 核对根元素和规则 |
代码调用 resources.getXml(R.xml.xxx) |
应用主动解析 XML 资源 | 从调用点确认预期结构和读取时机 |
xml/ 中存在文件但全项目无引用 |
文件可能尚未生效或已废弃 | 搜索资源名后再决定是否保留 |
| FileProvider、网络安全或备份行为异常 | 相关结构化配置可能错误 | 同时检查 XML 内容和引用它的 Manifest 属性或 meta-data |
常见文件包括网络安全配置、备份规则和 FileProvider 路径声明。它们虽然都位于 res/xml/,但语义由引用它们的 API 决定,不能根据目录名推断统一格式。
主示例
下面定义一个网络安全配置,明确禁止应用使用明文 HTTP:
<!-- res/xml/network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<base-config cleartextTrafficPermitted="false" />
</network-security-config>还需要由 AndroidManifest.xml 中的应用节点显式引用:
<application
android:networkSecurityConfig="@xml/network_security_config"
android:theme="@style/Theme.App">
<!-- 其他组件声明 -->
</application>生效行为:应用使用该网络安全配置,明文 HTTP 连接会受到这里的策略约束。仅创建 network_security_config.xml 而不引用它,不会让这份配置自动参与应用网络策略。
验证时可先在项目中搜索 @xml/network_security_config,确认引用链存在,再运行应用验证目标网络请求。若连接失败,还应结合请求 URL、目标 SDK、网络库错误信息和设备网络状态判断,不能仅凭 res/xml/ 中存在文件就认定配置已生效。
xml 与其他资源目录的区别
res/xml/ 中的文件会进入 Android 资源表,并可通过资源 ID 获取。若目标只是保存无需资源系统解释的原始文件,通常应根据读取方式考虑 res/raw/ 或 assets/;不要把任意 XML 文件都机械放进 res/xml/。
文件名会形成资源标识符,因此应使用符合 Android 资源命名规则的小写字母、数字和下划线。引用时省略扩展名,例如文件 network_security_config.xml 对应 @xml/network_security_config。
排查顺序
配置不生效时先搜索资源名,确认 Manifest、组件或代码确实存在引用;再检查 XML 的根元素和属性是否符合对应 API 的格式要求。若构建阶段直接报资源解析错误,则优先检查 XML 语法、资源引用和文件名,而不是运行时逻辑。
按原始文件名和目录结构打包资源,适合 HTML、JSON 或离线文件;其中内容会进入安装包,因此不能把 API Secret 等机密放在这里。
assets 目录
src/main/assets/ 用于随应用打包不需要生成 R 资源 ID 的原始文件。它最大的特点是保留文件名和子目录结构,运行时通过 AssetManager 按路径读取,因此适合离线网页、JSON、字体或成组静态文件。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
| 需要保留多级目录 | assets 可按相对路径访问文件 |
放入 src/main/assets/ |
| 代码通过字符串路径定位 | 不会生成 R.xxx 标识符 |
使用 context.assets.open() |
| 文件需要由 WebView 或解析器按原名读取 | 原始路径比资源 ID 更重要 | 优先使用 assets |
| 内容包含密钥或 API Secret | 文件最终进入安装包,可被提取 | 不要随 APK/AAB 打包机密 |
读取示例
假设项目中存在 src/main/assets/offline/config.json,内容如下。下面 Kotlin 为片段示例,运行环境需要提供 Android Context;在 Activity 中可直接使用 assets。
{"mode":"offline"}// assets 使用相对于 src/main/assets/ 的路径,并保留子目录。
val text = assets.open("offline/config.json")
.bufferedReader()
.use { it.readText() }
println(text)预期输出:
{"mode":"offline"}如果路径拼写错误或目标文件不存在,open() 会抛出 IOException;路径大小写也应与实际文件保持一致。
与 raw 的边界
需要 R.raw.xxx 这种编译期资源引用时应选择 res/raw/;需要保留目录层级、文件名,并按字符串路径访问时选择 assets/。不要仅因为文件是“原始文件”就默认放进 assets,关键区别是访问方式和目录需求。
适用范围
该目录属于 Android Gradle 项目的标准源码集资源位置,主源码集通常为 app/src/main/assets/,构建变体也可以在对应 source set 下提供同名目录。最终资源会进入应用制品,但这不提供保密能力。
保存不需要进一步资源转换的文件,同时仍可通过 R.raw 引用;音频、证书模板或固定数据文件等场景较常见。
raw 目录
src/main/res/raw/ 保存希望作为 Android 资源管理、又需要以原始字节或流读取的文件。构建时系统会为文件生成 R.raw 资源 ID,因此代码不必依赖字符串路径,适合固定音频、JSON 数据、模板或公开证书文件。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
希望通过 R.raw.xxx 引用 |
文件参与 Android 资源编译并生成 ID | 放入 res/raw/ |
| 不需要多级目录结构 | raw 更适合平铺的资源集合 |
使用合法资源文件名区分文件 |
需要 InputStream 读取固定文件 |
可用 openRawResource() |
通过资源 ID 打开 |
| 文件包含私钥、令牌或 Secret | 打包资源仍可从应用制品中提取 | 不要把机密放进 raw |
读取示例
假设存在 src/main/res/raw/default_config.json,文件名使用小写字母、数字和下划线等 Android 资源命名允许的形式。下面 Kotlin 为片段示例,运行环境需要提供 Android Context 或 Resources。
{"environment":"demo"}// 文件 default_config.json 会生成资源标识符 R.raw.default_config。
val text = resources.openRawResource(R.raw.default_config)
.bufferedReader()
.use { it.readText() }
println(text)预期输出:
{"environment":"demo"}资源在编译期不存在或名称不合法时,通常会在资源处理或代码编译阶段暴露问题;这也是 R.raw 相比字符串路径的一项优势。
与 assets 的边界
raw 的核心价值是资源 ID,而不是保留原始目录结构。若调用方需要访问 docs/help/index.html 这类多级路径,通常应改用 assets;若只需稳定引用一个固定文件,R.raw.default_config 更容易获得编译期检查。
适用范围
该规则适用于 Android 标准资源系统中的 res/raw/。文件会被包含进应用制品,因此“通过 R.raw 访问”不等于“内容安全”;公开证书可以随包分发,但私钥、API Secret 和长期凭据应存放在受控服务端或其他安全机制中。
按 ABI 保存预编译的 .so Native 动态库,例如 arm64-v8a 和 x86_64;排查第三方 SDK、ABI 缺失或 UnsatisfiedLinkError 时重点检查。
jniLibs 目录
jniLibs 用于把预编译的 Android Native .so 库纳入应用打包。默认主源码集通常放在 app/src/main/jniLibs/<ABI>/,同一个 Native 库如果需要支持多种 CPU 架构,应在对应 ABI 目录分别提供兼容版本。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
arm64-v8a/libvendor.so |
提供 64 位 ARM 版本 | 在 arm64 真机或对应模拟器上验证 |
缺少 x86_64 目录 |
x86_64 模拟器可能没有可加载的库 | 改用受支持 ABI 的设备,或向 SDK 提供方取得对应版本 |
| 文件存在但 APK 中没有 | 可能被 ABI 过滤、变体配置或打包规则排除 | 直接检查最终 APK,而不是只看源码目录 |
运行时报 UnsatisfiedLinkError |
常见于库未打包、ABI 不匹配或其依赖库缺失 | 依次核对设备 ABI、APK 内容和 Native 依赖链 |
运行时调用 System.loadLibrary("vendor") 时,Android 查找的是与当前设备 ABI 匹配的 libvendor.so。因此“源码目录里有文件”并不能单独证明运行时一定能够加载。
快速确认
在未启用自定义 APK 输出路径的普通 debug 构建中,可以先构建,再查看 APK 实际包含的 Native 库:
./gradlew :app:assembleDebug &&
unzip -Z1 app/build/outputs/apk/debug/app-debug.apk | grep -E '^lib/.+\.so$'预期结果(仅列关键行,Gradle 任务日志会因版本而异):
BUILD SUCCESSFUL in <TIME>
lib/arm64-v8a/libvendor.so
lib/x86_64/libvendor.so实际 ABI、库名和构建耗时可能不同。如果源码中存在某个 .so,但 APK 的 lib/<ABI>/ 下没有它,应继续检查 abiFilters、变体源码集以及 Native 打包配置。
适用范围
jniLibs 是 Android Gradle Plugin 源码集约定的一部分,但并不是 Native 库的唯一来源。通过 AAR 引入的 SDK 也可以自带 jni/<ABI>/*.so,CMake 或 externalNativeBuild 构建出的库通常来自构建流程而非手工维护的 jniLibs。
排查 Native 加载问题时,应同时确认设备 ABI、最终 APK/AAB 实际内容以及库自身依赖;只检查 app/src/main/jniLibs 容易漏掉由依赖或构建系统引入的 Native 库。
保存项目直接引用的本地 JAR 或 AAR 依赖,常见于厂商 SDK;升级或排查第三方库版本时需要同时检查 Gradle 依赖声明。
app/libs
app/libs 常用于保存厂商直接提供的本地 JAR 或 AAR,但目录中的文件不会因为“放进去了”就必然成为依赖;是否参与编译和打包,取决于模块的 Gradle 依赖声明。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
libs/vendor-util.jar |
本地 JVM 字节码依赖 | 检查 dependencies 是否引用该文件 |
libs/vendor-sdk.aar |
本地 Android Library,可包含资源、Manifest 和 Native 库 | 同时检查 Gradle 声明以及 AAR 内容 |
| 文件已替换但代码仍表现为旧版本 | Gradle 声明可能仍指向旧文件,或存在同名远程依赖 | 核对文件名、依赖树并清理重复来源 |
| 出现 duplicate class | 同一库可能同时来自 libs 和 Maven 仓库 |
保留单一依赖来源并重新构建 |
JAR 主要承载 JVM 类和普通资源;AAR 是 Android Library 包,还可以包含 Android 资源、Manifest、ProGuard 规则以及 jni/<ABI>/*.so。因此第三方 SDK 的 Native 问题有时来自 app/libs 中的 AAR,而不是项目自己的 jniLibs。
Gradle 声明
下面是 app/build.gradle.kts 中直接引用两个本地文件的片段示例,依赖的文件必须已经存在于 app/libs:
dependencies {
implementation(files("libs/vendor-sdk.aar"))
implementation(files("libs/vendor-util.jar"))
}这段配置生效后,Gradle 会把文件依赖加入对应模块的依赖解析和构建过程。修改文件名、移动目录或升级厂商包时,应同步修改这里的路径。
快速确认
完成依赖声明后,可直接构建应用验证 Gradle 是否能够解析并使用这些本地文件:
./gradlew :app:assembleDebug --console=plain预期结果(中间任务列表因 Gradle 与 AGP 版本而异):
BUILD SUCCESSFUL in <TIME>如果文件不存在或 AAR/JAR 无法被正确读取,构建通常会在依赖解析、编译或打包阶段失败。若构建成功但运行时仍找不到类或资源,还应检查实际使用的变体、重复依赖和厂商 SDK 的初始化要求。
使用边界
app/libs 是常见项目约定,不是一个能够自动提供版本元数据和传递依赖的远程仓库。厂商同时提供 Maven 坐标时,通常优先使用仓库依赖,因为 Gradle 可以获得版本、传递依赖和模块元数据。
必须使用本地二进制包时,应把“目录中的实际文件”和“Gradle 中的依赖声明”一起检查。升级 SDK 只替换 AAR/JAR、不核对声明与重复依赖,是本地依赖最常见的版本错乱来源。
测试与构建产物
保存主要运行在本地 JVM 上的单元测试,不依赖真实 Android 设备;适合测试业务逻辑、工具类和可脱离 Android Framework 的代码。
src/test
src/test 是 Android 模块的本地单元测试源集,测试通常由宿主机 JVM 执行,不需要启动模拟器或连接真实设备。适合验证纯 Kotlin/Java 业务逻辑、数据转换、算法以及能够通过替身隔离 Android 依赖的代码。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
路径位于 src/test/java 或 src/test/kotlin |
属于本地 JVM 测试 | 优先测试不依赖设备状态的逻辑 |
测试需要真实 Activity、系统服务或设备能力 |
本地 JVM 环境通常不足 | 改放 src/androidTest,或明确采用适合本地测试的模拟方案 |
| 测试执行速度快且无需设备 | 符合本地单元测试特征 | 适合加入频繁执行的开发与 CI 检查 |
| 代码只需普通 JUnit、Mock 或纯 JVM 依赖 | 不需要 Android Instrumentation | 保留在 src/test |
快速确认
在采用常见 debug 构建变体的 Android 模块中,可以执行本地单元测试任务:
./gradlew testDebugUnitTest预期结果:Gradle 在本机 JVM 中执行对应测试;全部通过时构建任务成功。实际任务名称会随模块和构建变体不同而变化。
BUILD SUCCESSFUL放什么,不放什么
优先放置 ViewModel 中可脱离 Android 运行的状态计算、Repository 的纯逻辑、格式化函数、校验器和其他普通 Kotlin/Java 类测试。若被测代码直接依赖真实设备上的 Context、UI、权限、传感器或系统组件,仅靠本地 JVM 往往不能还原真实行为。
本地测试也并非绝对不能接触 Android API:项目可以借助 Mock、Fake 或 Robolectric 等方案提供替代环境,但应明确这种测试与真实设备 Instrumentation 测试的边界。
适用范围
src/test 属于 Android Gradle Plugin 的测试源集约定;常见变体还可能出现 src/testDebug、src/testRelease 等更具体的测试源集。排查测试未被发现时,先确认文件是否位于正确模块和源集,再检查测试框架依赖与对应 Gradle 测试任务。
保存运行在模拟器或真实 Android 设备上的 Instrumentation 测试;涉及 Context、Activity、UI 或系统能力的测试通常放在这里。
src/androidTest
src/androidTest 是 Android 模块的设备端 Instrumentation 测试源集,测试 APK 会部署到模拟器或真实设备,并在 Android 运行环境中执行。需要真实 Context、Activity 生命周期、UI、权限或系统服务时,通常应从这里开始判断。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
路径位于 src/androidTest/java 或 src/androidTest/kotlin |
属于设备端测试 | 准备可用模拟器或真实设备 |
测试依赖 Context、Activity、Fragment 或系统服务 |
需要 Android 运行环境 | 使用 Instrumentation 测试 |
| 需要点击控件、检查页面状态或验证导航 | 属于 UI/交互验证 | 使用 Espresso、Compose 测试等设备端测试工具 |
| 测试只验证纯业务计算 | 设备环境没有必要 | 优先移到 src/test,缩短执行时间 |
快速确认
先确保至少有一台已启动并可被 ADB 识别的设备,然后执行常见 debug 变体的连接设备测试任务:
./gradlew connectedDebugAndroidTest预期结果:Gradle 构建应用与测试 APK,将它们安装到已连接设备或模拟器并执行 Instrumentation 测试;全部测试通过时任务成功。实际输出会包含设备、测试数量等动态信息。
BUILD SUCCESSFUL运行条件
设备端测试通常需要项目配置测试运行器,例如 androidx.test.runner.AndroidJUnitRunner,并声明相应的 AndroidX Test、Espresso 或 Compose 测试依赖。是否需要这些具体库取决于测试内容;仅因为文件位于 androidTest 并不会自动提供所有测试 API。
执行失败时先区分环境问题和测试问题:设备未连接、模拟器未启动、安装失败、权限或系统版本不匹配都可能导致测试尚未进入断言阶段。若测试逻辑本身不依赖 Android 环境,则不应为了方便而全部堆到设备测试中。
适用范围
src/androidTest 是 Android Gradle Plugin 的 Instrumentation 测试源集约定,也可以存在 src/androidTestDebug 等变体专用源集。多设备或托管设备场景可能使用不同 Gradle 任务,因此排查时应结合当前模块、构建变体和项目启用的测试设备配置确认实际任务名称。
保存编译生成的中间文件、代码和输出产物,可以通过重新构建生成;通常不提交 Git,遇到缓存异常时也常作为清理对象。
build 目录
build 是 Gradle 和 Android Gradle Plugin 在构建过程中写入生成内容的目录。Android 多模块项目通常会在各模块下形成自己的 build,例如 app/build;其中可能包含生成代码、中间文件、测试结果和最终构建产物。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
app/build、library/build |
对应模块的构建目录 | 排查某个模块时优先查看该模块目录 |
generated、intermediates 等子目录 |
插件或任务产生的生成文件、中间结果 | 不要直接维护这些文件,应修改源代码或构建配置 |
outputs 子目录 |
APK、AAB、映射文件等输出的常见入口 | 查找可安装包或发布产物时继续进入 outputs |
| 删除后重新构建可恢复 | 内容属于构建生成物 | 通常不提交 Git,可在异常排查时清理后重建 |
具体子目录名称由 Gradle、Android Gradle Plugin、启用的插件及实际执行任务决定,不应依赖某个中间目录在所有版本中永久存在。
快速确认
下面以常见的 app 模块为例执行 Debug 构建,并确认模块构建目录已经生成。命令假设使用 Bash 兼容终端;模块路径不同时将 :app: 和 app/build 替换为实际值。
./gradlew :app:assembleDebug >/dev/null && test -d app/build && echo "app/build exists"预期输出:
app/build exists如果构建失败,后面的目录检查不会执行,应先查看 Gradle 输出中的实际错误。
清理时怎么处理
需要验证问题是否来自旧的模块构建结果时,可运行该模块的 clean 任务,而不是手工修改 build 内的生成文件。
./gradlew :app:clean >/dev/null && test ! -d app/build && echo "app/build removed"预期输出:
app/build removedclean 删除的是对应项目或模块配置的构建目录,随后再次构建会重新生成所需内容。若项目通过 Gradle 配置修改了 buildDirectory,实际位置可能不再是默认的 build。
适用范围
这里描述的是 Gradle/Android Gradle Plugin 的构建输出目录,不要与项目根目录下用于 Gradle 本地状态和缓存的 .gradle 目录混淆。版本升级或第三方插件可能改变内部子目录,因此排障时应关注任务和产物类型,而不是长期依赖某条固定的内部路径。
位于模块 build 目录下,常用于保存 APK、AAB、映射文件等最终输出;查找可安装包或发布包时通常从这里定位。
outputs 目录
outputs 通常位于模块的 build 目录下,是查找面向安装、发布或后续处理的构建产物时最常用的入口。对于 Android 应用模块,APK、AAB 以及部分构建附属文件通常可以从这里继续定位。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
outputs/apk/... |
APK 构建结果 | 安装到设备或分发测试包时从这里查找 |
outputs/bundle/... |
Android App Bundle 构建结果 | 准备应用商店发布包时从这里查找 .aab |
mapping.txt |
代码压缩或混淆任务生成的映射文件 | 发布开启压缩的版本时与对应构建产物一起归档 |
| 找不到预期文件 | 对应变体或任务可能尚未执行,或输出位置受插件配置影响 | 先确认执行的构建任务、模块、Build Type 和 Product Flavor |
outputs 的内部层级并不是跨 Android Gradle Plugin 版本完全固定的公共接口,第三方插件或自定义构建逻辑也可能增加、移动或重命名产物。
快速定位 APK
下面构建常见的 app 模块 Debug 变体,再从 outputs 下查找 APK。模块名、变体和最终文件名都可能因项目配置而不同。
./gradlew :app:assembleDebug >/dev/null
find app/build/outputs -type f -name '*.apk' -print预期输出:默认应用模块常见结果如下;若项目修改了模块名、Flavor 或输出名称,实际路径会不同。
app/build/outputs/apk/debug/app-debug.apk如果需要 AAB,应执行对应 Bundle 任务,例如 :app:bundleRelease,再在 outputs 下查找 .aab,不要把 Debug APK 当作商店发布包。
找不到产物时
先确认构建任务确实成功,再确认查找的是正确模块和变体。assembleDebug、assembleRelease、bundleRelease 产生的文件类型和目录不同;启用 Product Flavor 后,路径中通常还会体现具体变体。
find app/build/outputs -type f \( -name '*.apk' -o -name '*.aab' -o -name 'mapping.txt' \) -print预期输出:只会列出当前已经生成且满足条件的文件;例如同时存在发布 Bundle 和映射文件时可能看到:
app/build/outputs/bundle/release/app-release.aab
app/build/outputs/mapping/release/mapping.txt若没有任何输出,不代表 Gradle 本身一定异常,更常见的是对应任务尚未执行、变体名称不同,或项目通过插件和自定义配置改变了产物位置。
适用范围
outputs 适合做“构建完成后去哪里找结果”的定位入口,但不应把其中每一级目录写死到长期脚本中。自动化发布流程更适合根据明确的构建任务和当前 Android Gradle Plugin 行为定位产物,并在版本升级后重新验证路径。
仓库整理与安全检查
保存 Gradle 构建缓存和本地状态,可由 Gradle 重新生成;通常不提交仓库,构建状态异常时可以在停止相关进程后清理。
.gradle 目录
项目根目录下的 .gradle 主要保存 Gradle 为当前项目生成的本地状态和缓存。它通常不属于项目源码,删除后 Gradle 会在后续构建时重新创建;排查异常时应区分项目内 .gradle 与用户目录下的 ~/.gradle,不要直接把两者一起删除。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
位于项目根目录的 .gradle/ |
当前项目的 Gradle 本地状态 | 通常加入忽略规则,不提交仓库 |
| 删除后再次执行 Gradle 又出现 | 属于可重新生成的数据 | 属正常现象,无需手工恢复 |
| 构建状态异常、缓存疑似损坏 | 本地状态可能与当前配置不一致 | 先停止相关 Gradle 进程,再清理项目级目录 |
~/.gradle/ |
用户级 Gradle 缓存、Wrapper 与全局状态 | 不要与项目级 .gradle 混为一谈 |
清理与验证
在项目根目录执行下面的 Bash 命令。它只删除当前项目的 .gradle,不会删除用户目录中的 Gradle 缓存。
./gradlew --stop
rm -rf .gradle
./gradlew help --quiet >/dev/null && test -d .gradle && printf '.gradle recreated\n'预期输出:Gradle 能正常启动时,最后会确认项目级目录已经重新生成。
.gradle recreated./gradlew --stop 的停止信息与守护进程数量可能因环境不同而变化,因此示例只验证最终状态。
处理边界
清理 .gradle 适合处理本地状态异常、缓存损坏或升级 Gradle 后出现的可疑构建问题,但它不是所有构建错误的通用修复手段。依赖解析失败、插件版本不兼容或源码错误仍应根据实际错误继续排查。
适用范围
这里指 Android 或其他 Gradle 项目根目录生成的 .gradle/。具体子目录名称和内部格式会随 Gradle 版本变化,不应让业务脚本依赖其中的私有文件结构。
保存 Android Studio 与 IntelliJ 的项目配置,其中部分文件可共享、部分属于个人环境;是否提交应按团队统一的 .gitignore 规则决定。
.idea 目录
.idea 保存 Android Studio 与 IntelliJ IDEA 为项目维护的 IDE 配置。它不是一个可以简单判定为“全部提交”或“全部忽略”的目录:部分配置可能用于团队共享,另一些文件记录个人工作区状态,最终应以项目现有的版本控制规则为准。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
项目已经跟踪某些 .idea 文件 |
团队可能有意共享这些项目配置 | 不要自行批量删除或取消跟踪 |
.idea/workspace.xml 被忽略 |
个人工作区状态不进入仓库 | 保持忽略,不作为团队配置提交 |
| 新生成文件未被忽略 | 当前 .gitignore 没有匹配它 |
先确认文件用途,再决定是否调整规则 |
| 不同成员频繁出现 IDE 配置冲突 | 共享范围可能过宽 | 统一团队规则并减少个人状态文件的跟踪 |
快速确认忽略规则
可以让 Git 直接判断典型的个人工作区文件是否被当前仓库规则忽略,而不是只凭文件名猜测。
if git check-ignore -q .idea/workspace.xml; then
printf 'workspace.xml is ignored\n'
else
printf 'workspace.xml is not ignored\n'
fi预期输出:如果团队规则已经忽略该文件,会看到下面的结果;否则输出中的 is ignored 会变为 is not ignored。
workspace.xml is ignored需要追查具体由哪条规则命中时,可进一步执行 git check-ignore -v .idea/workspace.xml,它会显示对应忽略文件、行号和模式。
提交策略
不要为了保持仓库整洁而直接忽略整个 .idea/,也不要把目录中的所有文件无条件提交。更稳妥的做法是继承项目已有规则,只共享团队明确需要的项目设置,并排除个人工作区、临时状态和机器相关配置。
适用范围
.idea 的具体文件组成会随 Android Studio、IntelliJ 平台版本以及启用的插件变化。判断某个文件是否应提交时,应优先参考当前项目的版本控制约定和所用 IDE 版本,而不是把网上某一份固定文件清单当作通用标准。
声明 Git 不应跟踪的本地配置、缓存、构建产物和敏感文件;整理 Android 仓库时应确保 build、local.properties 等内容被正确排除。
.gitignore
.gitignore 用来声明不应进入 Git 历史的本地配置、IDE 状态、缓存和构建产物。Android 项目中应重点排除 local.properties、各级 build/、Gradle 本地状态等机器相关文件,同时避免误排源码、Gradle Wrapper 和团队需要共享的配置。
常见规则
| 规则 | 含义 | 建议动作 |
|---|---|---|
local.properties |
通常包含本机 Android SDK 路径 | 排除,不应作为跨机器配置提交 |
.gradle/ |
Gradle 本地缓存与状态 | 排除 |
build/ |
当前目录下的构建产物 | 排除;多模块项目还应覆盖模块构建目录 |
.idea/ |
Android Studio 项目状态 | 是否整体排除取决于团队策略,部分项目会提交可共享配置 |
*.iml |
IDE 模块文件 | 现代 Gradle Android 项目通常不需要提交 |
一个常见的项目级配置可以写成:
.gradle/
local.properties
.idea/
*.iml
build/
**/build/这些规则只决定未跟踪文件是否被 Git 忽略,不会自动移除已经进入版本历史的文件。
快速确认
可用 git check-ignore 检查某个路径命中了哪条规则:
git check-ignore -v app/build/outputs/apk/debug/app-debug.apk local.properties预期输出:如果文件被忽略,会显示匹配它的 .gitignore 文件、规则所在行以及目标路径,例如:
.gitignore:<ID>:**/build/ app/build/outputs/apk/debug/app-debug.apk
.gitignore:<ID>:local.properties local.properties其中 <ID> 代表实际行号,具体值随文件内容变化;没有任何输出通常表示该路径未命中忽略规则。
已经被跟踪怎么办
.gitignore 对已经纳入索引的文件无效。若 local.properties 或构建产物曾经提交过,应先从 Git 索引移除,再保留工作区文件:
git rm --cached local.properties
git status --short预期输出:git status 会显示 local.properties 从索引中删除;文件仍保留在本地工作区。提交这次变更后,后续只要 .gitignore 规则仍然匹配,它就不会再次被普通 git add 纳入。
保存应用自定义的 R8 或 ProGuard 保留与优化规则;release 构建出现反射、序列化或第三方 SDK 类被裁剪问题时应重点检查。
proguard-rules.pro
proguard-rules.pro 保存应用自己的代码压缩、优化、混淆和保留规则。现代 Android 构建通常由 R8 执行这些规则;当 release 构建启用代码收缩后出现反射类找不到、序列化字段丢失或第三方 SDK 异常,应重点检查这里以及依赖随库提供的 consumer rules。
规则怎么判读
| 规则 | 作用 | 常见场景 |
|---|---|---|
-keep |
保留匹配的类或成员,并阻止相关优化或重命名 | 运行时通过反射按名称查找类型 |
-keepclassmembers |
保留指定成员,但不一定保留整个类 | 反射访问字段、方法或构造器 |
-keepattributes |
保留字节码属性 | 泛型签名、注解等运行时元数据被框架依赖 |
-dontwarn |
忽略匹配类的警告 | 仅在确认缺失类型不会进入实际执行路径时使用 |
不要用大范围 -keep class ** { *; } 作为通用修复,它会显著削弱代码收缩和混淆效果,并掩盖真正缺失的规则。
典型配置
以下为片段示例,假设应用确实通过反射读取带 @KeepForReflection 注解的类;实际包名和注解应替换为项目中真实存在的类型:
-keep @com.example.KeepForReflection class * {
*;
}
-keepattributes RuntimeVisibleAnnotations,RuntimeInvisibleAnnotations生效行为:匹配注解的类及其成员会被保留,指定的运行时注解属性也会继续存在。规则应尽量缩小到真实需要反射或按名称访问的范围,而不是保留整个应用包。
确认是否真正参与 release 构建
规则文件本身只有在对应构建类型启用了代码收缩并被 proguardFiles 引用时才会参与处理。常见的 Kotlin DSL 配置如下:
android {
buildTypes {
release {
isMinifyEnabled = true
proguardFiles(
getDefaultProguardFile("proguard-android-optimize.txt"),
"proguard-rules.pro"
)
}
}
}这是配置片段,需放在 Android 应用模块的 build.gradle.kts 对应 android 配置中。可执行 release 构建进行验证:
./gradlew assembleRelease预期结果:构建成功时 Gradle 以 BUILD SUCCESSFUL 结束,并生成对应 release 产物;具体任务数量、耗时和输出路径会因项目与 Android Gradle Plugin 版本不同而变化。
release 才出错时怎么查
先确认问题是否只在 isMinifyEnabled = true 时出现,再根据异常中的类名、方法名或反射目标缩小规则范围。若第三方 SDK 官方文档提供 R8 或 ProGuard 配置,应优先采用其规则;如果库已经通过 consumer rules 携带必要配置,应用通常不需要重复添加。
配置明文 HTTP、证书信任和部分网络安全策略,并通过 Manifest 引用;安全审查或排查 HTTPS 连接差异时值得优先检查。
network_security_config.xml
network_security_config.xml 用来声明应用的网络安全策略,常见用途是限制明文 HTTP、调整受信任 CA、为特定域名设置例外,以及在调试构建中临时信任用户证书。它通常放在 res/xml/,并由 Manifest 的 <application> 通过 android:networkSecurityConfig 引用。
怎么判读
| 配置线索 | 含义 | 建议动作 |
|---|---|---|
cleartextTrafficPermitted="false" |
禁止对应范围的明文 HTTP | 若业务仍访问 http://,改为 HTTPS;仅对确有需要的域名单独放行 |
<trust-anchors> |
指定系统 CA、自定义证书或其他信任来源 | HTTPS 握手异常时确认服务端证书链是否落在允许的信任源中 |
<domain-config> |
只对指定域名应用覆盖策略 | 检查域名是否写对,以及 includeSubdomains 是否符合实际请求 |
<debug-overrides> |
仅调试构建使用的额外信任配置 | 把抓包代理或测试 CA 限制在调试环境,不要扩大生产信任范围 |
<pin-set> |
对证书公钥做固定 | 证书更换前确认备用 pin 和有效期,避免正常轮换导致全量连接失败 |
典型配置
下面示例默认禁止明文流量,只为开发域名放行 HTTP,并让可调试构建额外信任用户安装的 CA:
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<base-config cleartextTrafficPermitted="false">
<trust-anchors>
<certificates src="system" />
</trust-anchors>
</base-config>
<domain-config cleartextTrafficPermitted="true">
<domain includeSubdomains="true">dev.example.com</domain>
</domain-config>
<debug-overrides>
<trust-anchors>
<certificates src="user" />
</trust-anchors>
</debug-overrides>
</network-security-config>Manifest 中还需要在 <application> 上设置 android:networkSecurityConfig="@xml/network_security_config";缺少引用时,这个文件不会自动生效。验证时可从应用分别请求允许的开发域名和其他 HTTP 域名:前者应按例外策略处理,后者应被明文策略阻止;HTTPS 请求则应按配置的信任锚和 pin 规则校验。
排查顺序
如果是 HTTP 被拒绝,先确认实际请求域名是否命中允许明文的 domain-config,再检查应用的 targetSdkVersion 和设备系统版本。Android 9(API 28)起,面向 API 28 及以上的应用默认不允许明文流量,因此旧项目升级目标版本后常出现行为变化。
如果是 HTTPS 失败,优先查看 trust-anchors、pin-set 和域名匹配,再结合握手异常判断是证书链、主机名、过期证书还是 pin 不匹配。debug-overrides 只应解决调试抓包等开发场景,不应作为生产证书问题的绕过方案。
保存 Android 应用签名私钥,release 密钥直接关系后续版本升级和身份可信性;不应随源码包公开或提交到公共代码仓库。
JKS 与 keystore 文件
Android 的发布签名通常依赖 keystore 文件保存私钥和证书条目。文件扩展名可能是 .jks 或 .keystore,但扩展名本身不能证明内部格式;JKS、PKCS12 等实际类型应通过工具确认。release 私钥一旦泄露或丢失,都会直接影响版本发布和签名身份管理。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
PrivateKeyEntry |
条目包含私钥,可用于签名 | 按高敏感凭据管理,限制访问并做好离线或受控备份 |
trustedCertEntry |
只有受信任证书,没有对应私钥 | 不能单独用于 APK/AAB 发布签名 |
| Alias | keystore 内条目的名称 | Gradle 签名配置中的 keyAlias 必须与目标私钥条目一致 |
| Store password | 保护 keystore 容器 | 不要硬编码进仓库;优先从受控密钥系统或本地安全变量注入 |
| Key password | 保护具体私钥条目 | 可能与 store password 相同,也可能独立设置 |
| SHA-256 指纹 | 标识签名证书 | 对接 API、OAuth、Firebase 等服务时常用于核对签名身份 |
快速确认
使用 JDK 自带的 keytool 查看 keystore 类型、Alias 和证书指纹,不会导出私钥:
keytool -list -v -keystore "<PATH>"预期输出:
Keystore type: <TYPE>
Keystore provider: <PROVIDER>
Your keystore contains <COUNT> entry
Alias name: <ID>
Entry type: PrivateKeyEntry
Certificate fingerprints:
SHA256: <FINGERPRINT>实际类型、条目数量、Alias 和指纹会因文件而异;如果提示密码错误、文件不存在或格式无法识别,应先确认路径、口令和 keystore 实际格式,而不是反复尝试修改文件。
Android 发布时看什么
传统本地签名模式下,同一应用后续版本通常需要继续使用与已发布版本一致的签名身份,否则系统不会把它视为可直接升级的同一应用。Gradle 的 signingConfigs 只是在构建时引用 keystore、Alias 和口令,真正敏感的是私钥材料本身。
使用 Google Play App Signing 时,应区分 app signing key 与 upload key:前者由 Google Play 用于给分发 APK 签名,后者用于验证开发者上传的 AAB/APK。此时本地保存的往往是 upload key,密钥轮换和恢复流程也与传统本地签名不同。
keystore.properties、signing.properties 等文件常保存签名路径、别名或密码;具体名称并非 Android 强制规定,应按敏感凭据处理。
签名属性文件
keystore.properties、signing.properties 一类文件通常由项目构建脚本自行读取,用于把签名路径、别名和密码与 build.gradle 分离。文件名和字段名都不是 Android 强制标准;判断它是否真正参与签名,要同时检查 Gradle 构建逻辑和版本控制状态。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
包含 storeFile、keyAlias 等字段 |
很可能保存签名配置 | 查找 Gradle 脚本在哪里读取这些字段 |
包含 storePassword、keyPassword |
含可直接使用的凭据 | 不提交仓库,不打印到构建日志 |
文件名出现在 .gitignore |
项目计划将其保留在本机 | 继续确认历史提交中是否曾泄露 |
| CI 中没有该文件 | 自动构建可能从环境变量或密钥服务取值 | 检查流水线的 Secret 注入方式 |
片段示例(仅展示常见字段,需由模块的 Gradle 构建脚本显式读取):
storeFile=<PATH>
storePassword=<SECRET>
keyAlias=<ALIAS>
keyPassword=<SECRET>这些键只是常见项目约定;单独创建该文件不会让 Android Gradle Plugin 自动启用签名。
快速确认
先检查敏感属性文件是否被 Git 忽略,不要为了验证而输出文件内容或真实密码。
git check-ignore -v keystore.properties signing.properties预期输出:被忽略的文件会显示匹配规则;实际行号可能不同。
.gitignore:<LINE>:keystore.properties keystore.properties
.gitignore:<LINE>:signing.properties signing.properties若某个文件没有任何输出,应检查 .gitignore。已经提交过的敏感文件即使后来加入忽略规则,也不会自动从 Git 历史中消失。
建议动作
本地开发可让属性文件保持未跟踪状态,并限制文件权限;CI/CD 更适合从受控 Secret 或密钥管理系统注入密码。若凭据曾进入公共仓库、日志或不可信环境,应更换相关密码或签名材料,而不是只删除文件。
适用范围
这一判断适用于常见 Android Gradle 项目。keystore.properties、signing.properties 及字段名称均属于项目约定,最终应以当前项目的 settings.gradle(.kts)、模块构建脚本和 CI 配置实际读取方式为准。
core、network、feature-login 等目录通常代表独立 Gradle 模块,具体名称由项目自行约定;判断真实模块关系应结合 settings.gradle 查看。
多模块目录
项目根目录里的 core、network、feature-login 等名称常被用作 Gradle 模块,但目录名称本身不能证明模块身份。最可靠的判断依据是根项目的 settings.gradle 或 settings.gradle.kts:它决定哪些 project path 被纳入当前多项目构建。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
include(":core") |
:core 已注册为 Gradle 子项目 |
再确认对应目录和构建脚本存在 |
目录中有 build.gradle(.kts) |
具备独立构建配置的典型特征 | 结合 settings 判断是否真的被包含 |
只有 src/main 目录 |
可能只是普通目录或源码组织方式 | 不要仅凭目录名认定为模块 |
projectDir 被显式重定向 |
project path 与物理目录可能不同 | 以 settings 中映射关系为准 |
构建脚本出现 project(":network") |
模块之间存在 Gradle 项目依赖 | 继续检查依赖方向和配置类型 |
片段示例(项目根 settings.gradle.kts):
rootProject.name = "SampleApp"
include(":app")
include(":core")
include(":network")
include(":feature-login")这段配置只说明四个子项目被纳入构建,并不代表它们之间已经建立依赖。依赖关系要到各模块的 build.gradle(.kts) 中继续确认。

快速确认
可以让 Gradle 直接解析目标 project path。下面以 :core 为例;如果该模块已正确注册,properties 任务能够读取它的 path 属性。
./gradlew :core:properties --console=plain | grep '^path:'预期输出:
path: :core如果 Gradle 报告找不到 :core,先检查 settings.gradle(.kts) 中是否包含该模块,再检查 projectDir 是否指向了其他物理目录。
判断真实依赖
模块被 include 只表示它属于当前构建。若要判断谁依赖谁,应继续搜索模块构建脚本中的项目依赖声明,例如以下片段表示当前模块依赖 :network:
dependencies {
implementation(project(":network"))
}这是片段示例,需放在使用 Kotlin DSL 的模块级 build.gradle.kts 中;实际可用配置还取决于该模块应用的插件。
适用范围
上述规则适用于 Gradle multi-project build,包括 Android 常见的 Kotlin DSL 与 Groovy DSL 项目。core、network、feature-* 等只是命名习惯;真实模块集合、物理目录映射和依赖关系应分别以 settings.gradle(.kts) 与各模块构建脚本为准。