原生移动开发 / 知识点
Android 项目目录与文件用途速查
项目与 Gradle 配置
定义 Gradle 项目名称、参与构建的模块以及插件和依赖仓库配置;查看项目包含哪些 app、library 或 feature 模块时优先检查这里。
settings.gradle
settings.gradle 决定一次 Gradle 构建包含哪些模块,并可集中定义插件解析仓库和项目依赖仓库。遇到模块没有加入构建、插件找不到或仓库来源异常时,应优先核对这里,而不是先修改模块级 build.gradle。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
rootProject.name |
根项目名称 | 核对是否与当前工程预期一致 |
include ':app' |
将模块加入当前构建 | 模块目录存在但 Gradle 看不到时检查此项 |
pluginManagement |
插件解析规则和仓库 | 插件 ID 或插件版本无法解析时检查 |
dependencyResolutionManagement |
项目依赖仓库策略 | Maven 依赖解析失败或仓库来源不一致时检查 |
repositoriesMode |
约束模块是否可自行声明仓库 | 出现项目仓库被禁止等错误时核对策略 |
典型配置
下面是 Groovy DSL 的片段示例,假设工程确实存在 app 和 core 两个模块。
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
}
}
rootProject.name = "SampleApp"
include ':app', ':core'配置生效后,可直接让 Gradle 列出参与构建的项目:
./gradlew projects预期输出(关键行):
Root project 'SampleApp'
Project ':app'
Project ':core'
BUILD SUCCESSFUL实际输出还会包含 Gradle 的说明文字,版本不同可能略有差异;关键是目标模块出现在项目列表中且构建配置阶段成功。
常见判读与动作
模块目录已经存在但 projects 中没有它,通常是缺少对应 include,或声明的项目路径与目录结构不一致。插件解析失败时重点查看 pluginManagement.repositories;普通库依赖下载失败时则查看 dependencyResolutionManagement.repositories,不要混淆两类仓库。
使用 FAIL_ON_PROJECT_REPOS 后,模块级脚本再声明仓库可能直接导致构建失败。这通常是集中管理仓库的预期效果,应优先删除重复的模块仓库声明,而不是随意放宽策略。
适用范围
以上写法针对 Groovy DSL 的 settings.gradle。Kotlin DSL 对应文件通常为 settings.gradle.kts,语法不同。较新的 Gradle 与 Android 工程常把插件管理、依赖仓库和版本目录入口集中到 Settings;旧工程则可能仍在根目录构建脚本中保留部分仓库配置,排查时应结合项目实际版本判断。
保存项目级插件或共享构建配置,具体职责随 Gradle 和 Android Gradle Plugin 版本变化;排查插件版本、统一配置时需要查看。
根目录 build.gradle
根目录 build.gradle 是整个 Gradle 构建的项目级脚本入口之一,常用于声明供各模块使用的插件以及少量共享配置。现代 Android 工程通常会把仓库、版本和复杂公共逻辑分别迁移到 settings.gradle、Version Catalog 或 Convention Plugin,因此该文件可能非常精简。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
plugins 与 apply false |
注册插件但不在根项目直接应用 | 排查各模块引用的插件版本或别名 |
buildscript |
较旧的插件 classpath 配置方式 | 维护旧工程时核对插件依赖和仓库 |
allprojects、subprojects |
向多个项目批量施加配置 | 确认是否存在隐式配置或版本兼容问题 |
| 文件接近空白 | 配置已迁移到其他构建文件 | 继续检查 Settings、版本目录或 Convention Plugin |
典型配置
使用 Version Catalog 管理插件版本时,根目录脚本可以只注册插件,真正应用插件的工作交给具体模块。下面是依赖 gradle/libs.versions.toml 已定义相应别名的片段示例:
plugins {
alias(libs.plugins.android.application) apply false
alias(libs.plugins.android.library) apply false
alias(libs.plugins.kotlin.android) apply false
}apply false 表示 Gradle 解析并提供该插件,但不会把它应用到根项目。模块仍需在自己的 build.gradle 中显式应用所需插件。
修改根目录脚本后,可以先执行轻量任务验证整个构建脚本能否完成配置阶段:
./gradlew help预期输出(关键行):
BUILD SUCCESSFUL如果在任务执行前就出现插件别名不存在、插件无法解析或脚本语法错误,说明问题发生在构建配置阶段,应根据首个错误定位根脚本、版本目录或插件仓库配置。
常见判读与动作
看到 buildscript { dependencies { classpath ... } } 不代表配置一定错误,它通常来自较旧的 Android Gradle 工程。维护存量项目时先确认当前 Gradle、Android Gradle Plugin 和其他插件的兼容关系,再决定是否迁移到 plugins DSL,避免只改语法却没有同步版本和插件解析方式。
若根脚本中存在大量 subprojects 或 allprojects 配置,要特别留意这些规则会隐式影响所有模块。共享逻辑持续增长时,更适合迁移到 Convention Plugin,而不是继续把编译选项、依赖和 Android 配置堆在根脚本中。
适用范围
以上示例针对 Groovy DSL 的根目录 build.gradle。不同年代的 Gradle 与 Android Gradle Plugin 项目结构差异较大,因此不能仅凭根脚本是否包含仓库、插件版本或共享配置判断对错;应同时检查 settings.gradle、gradle/libs.versions.toml、buildSrc 或独立构建逻辑目录,确认配置实际由哪里提供。
使用 Kotlin DSL 编写的 Gradle 构建脚本,与 build.gradle 的 Groovy DSL 角色相近;项目采用 .kts 时不要再按 Groovy 语法修改。
build.gradle.kts
build.gradle.kts 是使用 Kotlin DSL 编写的 Gradle 构建脚本。它与 build.gradle 承担相近的构建职责,但语法、属性赋值和函数调用遵循 Kotlin 规则,不能直接粘贴 Groovy DSL 写法。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
文件名为 build.gradle.kts |
当前脚本使用 Kotlin DSL | 按 Kotlin 语法编辑 |
| 位于项目根目录 | 通常配置项目级插件或公共构建逻辑 | 修改前确认是否会影响所有模块 |
位于 app/ 等模块目录 |
通常配置该模块的插件、Android 参数和依赖 | 构建时使用对应模块路径验证 |
出现 plugins {}、dependencies {} |
正在声明插件或依赖 | 优先沿用项目现有写法和版本管理方式 |
示例来自 build.gradle |
很可能是 Groovy DSL | 不要未经转换直接复制到 .kts |
最常见的区别是 Kotlin DSL 使用 = 赋值,并使用 Kotlin 函数调用语法。例如 Groovy 中的 minSdk 24 不能机械照搬为 Kotlin DSL;实际属性名和写法还要以当前 Android Gradle Plugin 提供的 DSL 为准。
快速确认
下面是片段示例,假设项目已有 app/build.gradle.kts,在文件末尾临时注册一个任务,用来确认脚本能被 Kotlin DSL 正确解析:
tasks.register("printBuildScriptKind") {
doLast {
// 任务能执行,说明当前 .kts 脚本至少已通过配置阶段解析。
println("Kotlin DSL")
}
}在项目根目录执行:
./gradlew :app:printBuildScriptKind预期输出中应包含:
> Task :app:printBuildScriptKind
Kotlin DSL
BUILD SUCCESSFULGradle 版本、耗时和其他日志可能不同;关键是任务成功执行且没有 Kotlin DSL 编译错误。
修改时看什么
遇到 Unresolved reference、Expecting an element 或类型不匹配时,先检查示例是否来自 Groovy DSL,再确认对应插件已经应用。Kotlin DSL 具有静态类型检查,因此某个配置块不存在时,通常比 Groovy DSL 更早暴露问题。
如果项目使用 Version Catalog,依赖和插件可能写成 libs、alias(...) 等形式;如果项目直接写坐标,则可能出现 implementation("group:artifact:version")。两种方式都可能正确,应保持现有项目的版本管理风格,不要为了套用示例随意混用。
适用范围
.kts 表示 Kotlin Script,Gradle 的 Kotlin DSL 不只用于 Android 项目。具体可用的 android {}、插件 ID、属性名和依赖配置由 Gradle、Android Gradle Plugin 以及项目采用的其他插件共同决定,因此遇到 DSL 差异时应以当前项目插件版本对应的文档为准。
保存 Gradle JVM 参数和项目级构建属性,常用于内存、AndroidX 或自定义开关;可以提交仓库,但不应直接存放密码和私钥。
gradle.properties
项目根目录的 gradle.properties 用于保存 Gradle 构建属性和部分 JVM、Android 构建开关。它适合放可共享的构建参数,但不是秘密存储文件,不应把密码、访问令牌或私钥直接提交到其中。
怎么判读
| 配置或线索 | 含义 | 建议动作 |
|---|---|---|
org.gradle.jvmargs |
设置 Gradle Daemon 的 JVM 参数 | 内存不足时结合机器资源调整 |
android.useAndroidX=true |
告诉 Android 构建使用 AndroidX | 现代 AndroidX 项目通常保持启用 |
自定义 key=value |
定义 Gradle 属性 | 确认构建脚本确实读取了该键 |
| 属性只在某台机器需要 | 不适合作为仓库统一配置 | 优先放到用户级 Gradle 配置或其他本地配置 |
| 值包含密码、令牌或私钥 | 存在泄露风险 | 改用环境变量、受保护的 CI Secret 或专用秘密管理方案 |
gradle.properties 本质上只是属性来源之一。某个自定义键写进文件后不会自动产生业务效果,只有 Gradle、Android Gradle Plugin 或项目构建逻辑主动读取它时才会生效。
快速确认
例如在项目根目录加入一个无敏感信息的自定义开关:
org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8
android.useAndroidX=true
featureX.enabled=true可用 Gradle 的 properties 任务确认自定义属性已进入项目属性集合:
./gradlew properties | grep '^featureX.enabled:'预期输出:
featureX.enabled: true如果使用 Windows PowerShell,可改用等价的文本筛选命令;Gradle 的其他输出会随版本和项目配置变化。
常见失败怎么处理
修改 JVM 参数后仍然内存不足时,不要只持续增大 -Xmx。先确认实际报错发生在 Gradle Daemon、Kotlin 编译器还是其他构建进程,并检查机器可用内存;过大的堆上限同样可能造成系统换页和构建变慢。
自定义属性没有生效时,先检查键名是否完全一致,再确认构建脚本是否读取该属性。例如 Kotlin DSL 中常通过 providers.gradleProperty("featureX.enabled") 获取值。属性存在但无人读取时,构建行为不会改变。
敏感信息边界
仓库中的 gradle.properties 通常会随源码一起分发,因此只应保存团队可以共同看到的构建参数。个人凭据可放在用户级 Gradle 配置、环境变量或 CI/CD 的 Secret 存储中,并在构建脚本中按需读取。
具体 Android 属性由 Android Gradle Plugin 定义,Gradle 本身也有自己的标准属性;某个网上示例中的键并不代表所有 Gradle 或 AGP 版本都支持。遇到陌生属性时,应先确认其来源、适用插件和版本,再决定是否加入项目。
保存当前开发机器的 Android SDK 等本地路径,不属于项目业务配置;通常不提交 Git,换电脑或重新配置环境后可以重新生成。
local.properties
local.properties 用来保存当前开发机器才能确定的路径或本地环境信息。Android 项目里最常见的是 sdk.dir;它不应承担业务开关、服务器地址或团队共享配置,因为换一台电脑后这些值通常不同。
值与含义
| 线索 | 含义 | 建议动作 |
|---|---|---|
sdk.dir=<PATH> |
Android SDK 在本机的安装路径 | 指向实际 SDK 目录;环境迁移后重新生成或修改 |
| 文件只在本机存在 | 属于开发环境状态,而不是源码的一部分 | 通常保持在 .gitignore 中 |
| 出现团队自定义键 | 不一定是 Android 或 Gradle 通用字段 | 只有对应工具或插件文档明确要求时才使用 |
<PATH> 代表本机实际路径,不同开发者、操作系统和 CI 环境会不同。
快速确认
先查看文件中的 SDK 路径:
grep '^sdk.dir=' local.properties预期输出:
sdk.dir=<PATH>如果没有这一行,或路径指向不存在的目录,Gradle 同步和 Android 构建可能无法定位 SDK。可在 Android Studio 重新配置 SDK,或按当前机器的实际路径更新该文件。
Git 判读
local.properties 通常不提交 Git。原因不是文件“有秘密”,而是其中的路径具有机器相关性;把它提交后,其他开发者很容易得到无效路径。若文件已经被 Git 跟踪,仅把它加入 .gitignore 不会自动停止跟踪,需要先从索引中移除再保留本地文件。
适用范围
local.properties 是 Android Studio 与 Android Gradle 构建中常见的本机配置文件,但除 sdk.dir 等约定用途外,其他键是否有效取决于具体插件或工具。换电脑、重装 SDK 或重新导入项目后,该文件可以按新的本机环境重新生成。
保存 Gradle Wrapper 配置以及可能使用的版本目录文件,使团队能使用一致的 Gradle 版本;通常应随源码一起提交。
gradle 目录
项目根目录下的 gradle/ 主要保存 Gradle Wrapper 的内部文件,以及项目可选的集中式 Gradle 配置。它通常属于源码的一部分,应和项目一起提交,让开发机和 CI 能按同一套版本与配置工作。
常见内容
| 路径 | 含义 | 建议动作 |
|---|---|---|
gradle/wrapper/gradle-wrapper.properties |
指定 Wrapper 下载的 Gradle 发行版及相关参数 | 修改 Gradle 版本时重点检查 |
gradle/wrapper/gradle-wrapper.jar |
Wrapper 的启动代码 | 通常随源码提交,不手工改内容 |
gradle/libs.versions.toml |
项目启用 Version Catalog 时的依赖与插件版本目录 | 团队统一维护并提交 |
其他 gradle/ 下文件 |
可能来自依赖校验、初始化逻辑或项目自定义约定 | 先确认对应 Gradle 功能或插件来源 |
Wrapper 还包括项目根目录的 gradlew 和 gradlew.bat;它们属于同一套 Wrapper,但不在 gradle/ 目录内部。
快速确认
下面同时检查 Wrapper 指向的发行版,并用 Wrapper 启动 Gradle:
grep '^distributionUrl=' gradle/wrapper/gradle-wrapper.properties
./gradlew --version预期结果的关键行类似:
distributionUrl=https\://services.gradle.org/distributions/gradle-<VERSION>-bin.zip
Gradle <VERSION><VERSION> 会随项目设置变化。两处版本应对应同一个 Gradle 发行版;首次运行时,如果本机没有该版本,Wrapper 会先下载再启动。
怎么判读
若开发者直接使用系统安装的 gradle,实际版本可能和项目要求不一致;日常构建应优先使用 ./gradlew 或 Windows 下的 gradlew.bat。如果同步失败并提示 Gradle 版本不兼容,应先核对 gradle-wrapper.properties,再结合 Android Gradle Plugin 对 Gradle 的版本要求处理,而不是只升级其中一端。
libs.versions.toml 只有项目启用了 Version Catalog 时才会出现,不能把它视为所有 Android 项目的必备文件。它管理的是依赖与插件版本别名,不负责决定 Wrapper 使用哪个 Gradle 发行版。
适用范围
gradle/wrapper/* 属于 Gradle Wrapper 机制,Android 项目通常直接采用;libs.versions.toml 等额外文件则取决于项目使用的 Gradle 功能。除本机缓存或生成物外,这些项目级配置一般应纳入版本控制,以保证本地开发与 CI 的构建入口一致。
分别提供 Unix 类系统和 Windows 的 Gradle Wrapper 启动脚本,CI 与开发机都可据此执行统一版本的构建任务,通常需要提交。
gradlew 与 gradlew.bat
这两个文件是 Gradle Wrapper 的平台启动入口:Unix、Linux 与 macOS 通常执行 gradlew,Windows 执行 gradlew.bat。它们会按项目的 Wrapper 配置启动指定 Gradle 版本,避免开发机和 CI 因系统级 Gradle 版本不同而产生构建偏差。
值与含义
| 文件 | 运行环境 | 主要作用 | 建议动作 |
|---|---|---|---|
gradlew |
Unix、Linux、macOS 等 | 由 Shell 启动 Wrapper | 保留可执行权限并提交仓库 |
gradlew.bat |
Windows cmd、PowerShell |
由批处理脚本启动 Wrapper | 与 gradlew 一并提交仓库 |
何时出现
项目生成或启用 Gradle Wrapper 后,两个脚本通常位于仓库根目录,并与 gradle/wrapper/gradle-wrapper.jar、gradle/wrapper/gradle-wrapper.properties 配套存在。脚本本身不固定 Gradle 版本;真正的分发版本和下载地址由 gradle-wrapper.properties 决定。
快速确认
在 Unix 类系统从项目根目录执行:
./gradlew --version预期输出:关键行会显示 Wrapper 实际启动的 Gradle 版本;具体版本和操作系统信息以项目与机器为准。
Gradle <VERSION>
OS: <OS>Windows 使用对应的 gradlew.bat 入口做同一检查。只要版本查询能够成功结束,就说明启动脚本、Wrapper JAR 和分发配置至少已经完成了基本启动链路。
判读与处理
优先通过 Wrapper 执行 build、test、assemble 等任务,不要要求每台机器单独安装并维护同版本 Gradle。若脚本缺失,应先检查仓库是否漏提交;若 Unix 上提示没有执行权限,应恢复 gradlew 的可执行位,而不是改用系统 gradle 绕过 Wrapper。
适用范围
该判读适用于使用 Gradle Wrapper 的 Android/Gradle 工程。Android Studio 可以代为触发 Gradle,但命令行、自动化脚本和 CI 仍应以仓库中的 Wrapper 作为可复现构建入口。
集中维护依赖、插件和版本别名,供多个模块复用;项目启用 Gradle Version Catalog 时,升级依赖通常先从这个文件查起。
libs.versions.toml
libs.versions.toml 是 Gradle Version Catalog 的常用目录文件,用别名集中描述依赖、插件、版本和依赖组合。Android 多模块工程采用它后,模块构建脚本通常只引用别名,升级版本时优先检查这个文件即可定位共享版本来源。
值与含义
| 区段或字段 | 含义 | 常见动作 |
|---|---|---|
[versions] |
声明可复用的版本键 | 升级共享版本时先改这里 |
[libraries] |
把依赖坐标映射为别名 | 查模块依赖实际指向哪个组件 |
[bundles] |
把多个 library 别名组合成一组 | 成组引入依赖时检查成员是否完整 |
[plugins] |
把 Gradle 插件 ID 映射为别名 | 统一插件版本并供 plugins 块引用 |
version.ref |
引用 [versions] 中的版本键 |
避免多个别名重复写同一版本 |
何时出现
按 Gradle 的默认约定,目录文件通常位于 gradle/libs.versions.toml,默认目录名为 libs,因此构建脚本会生成类似 libs.junit、libs.plugins.<alias> 的类型安全访问器。项目也可以显式创建其他 Version Catalog;这时文件名、目录名和访问器前缀可能不同,不能把所有 TOML 文件都当成默认 libs。
主示例
片段示例:下面的 gradle/libs.versions.toml 定义 JUnit 版本和依赖别名;模块的 build.gradle.kts 再通过生成的 libs 访问器引用它。
[versions]
junit = "4.13.2"
[libraries]
junit = { module = "junit:junit", version.ref = "junit" }dependencies {
testImplementation(libs.junit)
}修改目录后,可先执行一个轻量 Gradle 任务验证 TOML 是否能被解析:
./gradlew help预期输出:如果目录语法和构建配置有效,命令最终应成功结束;耗时会因机器和缓存状态不同而变化。
BUILD SUCCESSFUL in <TIME>该检查主要验证配置阶段能否通过;真正的依赖版本仍应在对应编译、测试或依赖分析任务中确认。
判读与处理
遇到模块里看不到显式版本号时,先沿着 libs.<alias> 回查 [libraries] 或 [plugins],再根据 version.ref 找到 [versions] 的键。若访问器不存在,优先检查别名拼写、TOML 区段、文件位置以及当前构建是否确实加载了该 Catalog,而不是直接在模块脚本里硬编码版本。
适用范围
该条目描述 Gradle Version Catalog 的标准 TOML 用法和默认 libs 约定,适用于采用 Version Catalog 的 Android/Gradle 工程。具体插件、依赖版本能否使用,仍受项目的 Gradle、Android Gradle Plugin、JDK 与各库自身兼容范围约束。
应用模块与源码
通常代表可安装 Android 应用的主模块,内部包含源码、资源、Manifest 和模块构建配置;多数单应用项目的核心代码都从这里进入。
app 目录
app 通常是 Android 工程中使用 com.android.application 插件的应用模块目录。它集中保存应用源码、资源、Manifest、测试代码和模块级构建配置,但 app 只是惯用名称,并不是 Android Gradle Plugin 强制要求的模块名。
怎么判读
| 路径或文件 | 主要含义 | 看到问题时先检查 |
|---|---|---|
app/src/main/AndroidManifest.xml |
主源码集的 Manifest | 组件声明、权限、应用级属性是否正确 |
app/src/main/java/ 或 app/src/main/kotlin/ |
Kotlin、Java 源码 | 包路径、源码集和编译错误 |
app/src/main/res/ |
布局、字符串、图片等 Android 资源 | 资源名、限定符和资源引用 |
app/src/test/ |
本地 JVM 测试 | 测试源码是否放入正确源码集 |
app/src/androidTest/ |
设备或模拟器上的仪器测试 | 测试运行器和设备环境 |
app/build.gradle 或 app/build.gradle.kts |
模块级 Gradle 配置 | 插件、SDK、BuildType、依赖和打包配置 |
src/main 是默认主源码集;项目使用 product flavor、BuildType 或自定义 SourceSet 时,还可能出现 src/debug、src/release、src/<ID> 等目录,并在构建特定变体时与 main 合并。
快速确认
在项目根目录执行下面的 Bash 检查,可以确认典型应用模块至少具有 Manifest 和模块构建文件:
test -f app/src/main/AndroidManifest.xml && echo "manifest: ok"
if [ -f app/build.gradle ] || [ -f app/build.gradle.kts ]; then
echo "module build file: ok"
fi预期输出:
manifest: ok
module build file: ok若缺少其中一行,先确认模块是否真的名为 app;模块可能已改名,或者只包含库模块。模块是否参与构建还应检查根项目的 settings.gradle 或 settings.gradle.kts 是否包含对应模块。
排查顺序
遇到“源码明明存在却没有参与编译”时,先确认当前构建的是哪个模块和 Variant,再检查文件所在 SourceSet,最后查看模块构建脚本中的 sourceSets、flavor 与 BuildType 配置。不要仅凭目录名判断文件一定会进入当前 APK。
定义应用模块的 applicationId、SDK 版本、BuildType、签名、依赖和打包行为;排查版本号、依赖或 release 构建问题时重点查看。
app/build.gradle
app/build.gradle 是使用 Groovy DSL 时常见的应用模块构建脚本;采用 Kotlin DSL 的工程对应文件通常为 app/build.gradle.kts。这里决定该模块应用哪些插件、使用什么 Android SDK、如何生成不同构建变体,以及编译时引入哪些依赖。
怎么判读
| 配置位置 | 含义 | 常见排查方向 |
|---|---|---|
plugins |
为模块启用 Android、Kotlin 等插件 | 模块类型错误、插件未应用或版本不兼容 |
android.namespace |
模块代码和生成资源类使用的命名空间 | R、生成代码或包引用异常 |
compileSdk |
编译时使用的 Android API | 新 API 无法编译或依赖要求更高 SDK |
defaultConfig.applicationId |
安装包的应用标识 | 安装冲突、发布包标识或渠道包问题 |
minSdk / targetSdk |
最低支持版本与目标平台行为版本 | 兼容性、发布要求和运行行为变化 |
versionCode / versionName |
内部升级序号与用户可见版本 | 商店拒绝升级或版本显示不正确 |
buildTypes |
debug、release 等构建类型 |
混淆、调试开关、签名和资源压缩问题 |
dependencies |
模块编译和运行所需依赖 | 缺类、版本冲突和重复依赖 |
namespace 与 applicationId 不应混为一谈:前者属于代码和资源命名空间,后者标识最终安装的应用。不同 Variant 还可以通过 flavor 或 BuildType 对 applicationId、版本等进行追加或覆盖。
配置片段
下面是 Groovy DSL 的片段示例,依赖上下文是该文件已经作为 Android 应用模块的构建脚本使用;SDK 数字仅用于展示字段位置,应按项目实际要求设置。
plugins {
id 'com.android.application'
}
android {
namespace 'com.example.demo'
compileSdk 35
defaultConfig {
applicationId 'com.example.demo'
minSdk 24
targetSdk 35
versionCode 1
versionName '1.0'
}
buildTypes {
release {
minifyEnabled false
}
}
}
dependencies {
implementation 'androidx.core:core-ktx:1.15.0'
}生效行为:Gradle 会按该模块的插件、SDK、默认配置、BuildType 和依赖生成对应构建变体。修改后应执行 Gradle 同步,并通过实际构建确认配置可以被当前 Gradle 与 Android Gradle Plugin 版本解析。
验证与排查
在项目根目录执行应用模块的 Debug 构建,可以同时检查脚本语法、插件解析、依赖解析和大部分 Android 配置:
./gradlew :app:assembleDebug预期输出:成功时末尾应包含类似结果,耗时会因环境不同而变化:
BUILD SUCCESSFUL in <TIME>如果失败发生在脚本解析阶段,先查看报错指向的属性或 DSL;若发生在依赖解析阶段,再检查仓库与依赖版本;只有 release 失败时,则重点比较 buildTypes.release、签名、混淆和资源压缩配置。
保存应用正式构建使用的主要源码、资源和 Manifest,是阅读业务实现时最核心的 Source Set;测试代码不会放在这里。
src/main
src/main 是 Android Gradle 模块的主 Source Set,保存默认参与正式构建的 Manifest、源码和资源。排查某个类、资源或权限声明来自哪里时,通常先从这里开始,再检查构建类型和 Product Flavor 是否提供了覆盖内容。
主要内容
| 路径 | 含义 | 判读动作 |
|---|---|---|
src/main/AndroidManifest.xml |
主 Manifest | 查组件、权限和应用级声明 |
src/main/java/ |
Java 以及常见的 Kotlin 源码位置 | 查 Activity、Service、Repository 等实现 |
src/main/res/ |
Android 编译资源 | 查布局、字符串、图片和资源限定目录 |
src/main/assets/ |
原样打包的资产,可选 | 查运行时通过 AssetManager 读取的文件 |
实际项目还可能包含 jniLibs、aidl 等目录;是否存在取决于项目使用的能力,不应把缺少这些目录视为异常。
与其他 Source Set 的关系
main 提供各构建变体共享的基础内容。若项目存在 src/debug、src/release 或 Flavor 对应目录,Android Gradle Plugin 会在构建具体 Variant 时合并相应 Source Set,因此只查看 src/main 可能无法解释最终 APK 或 App Bundle 中的全部内容。
单元测试通常位于 src/test,设备或模拟器上的 instrumentation 测试通常位于 src/androidTest,它们不属于 src/main。
快速确认
在目标 Android 模块目录执行:
test -d src/main && printf 'src/main exists\n'预期输出:
src/main exists若没有输出,先确认当前终端是否位于正确模块;项目也可能通过 Gradle 自定义 Source Set 路径。
判读边界
src/main 描述的是默认源码集位置,不等于最终构建结果的完整来源。遇到同名资源、Manifest 属性或类在不同构建类型下表现不一致时,应继续检查对应的 build type、Flavor 及 Gradle Source Set 配置。
保存 Java 或 Kotlin 业务源码,目录名称为 java 并不代表只能放 Java 文件;Activity、Service、Repository 等通常都能从这里找到。
java 目录
src/main/java 是 Android 项目最常见的业务源码目录。虽然目录名叫 java,使用 Kotlin 的 Android 项目也经常把 .kt 文件放在这里,因此判断源码语言应查看文件扩展名,而不是只看目录名称。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
.java 文件 |
Java 源码 | 按包名继续定位类 |
.kt 文件 |
Kotlin 源码 | 同样可能位于 java 目录 |
| Activity、Service 等类 | Android 组件实现 | 再结合 Manifest 或调用关系确认入口 |
| Repository、UseCase、ViewModel 等 | 业务或架构代码 | 按包结构继续追踪依赖 |
目录中的多级文件夹通常按包名组织,例如 com/example/app 对应源码中的 com.example.app。这是常见约定,也便于 IDE 展示和检索。
快速确认
在 Android 模块目录执行下面的命令,可以同时查找 Java 与 Kotlin 文件:
find src/main/java -type f \( -name '*.java' -o -name '*.kt' \) | head -n 5预期输出示例,实际路径和文件名会不同:
src/main/java/<PATH>/MainActivity.kt
src/main/java/<PATH>/UserRepository.kt若目录存在但没有结果,可能是该模块暂时没有源码,也可能把 Kotlin 文件放在 src/main/kotlin 或自定义源码目录。
常见误判
不要因为目录名是 java 就认定其中不能出现 Kotlin,也不要把这里的所有类都视为业务代码;生成代码、基础设施实现或框架适配代码也可能位于同一 Source Set。
src/main/java 是 Android Gradle 项目的常见默认组织方式,而不是不可修改的固定路径。若源码在标准位置找不到,应继续检查模块的 Gradle Source Set 配置和项目实际目录结构。
部分项目会单独使用 kotlin 目录保存 Kotlin 源码,其作用与 java 源码目录相近;是否存在取决于项目约定和构建配置。
kotlin 目录
kotlin 目录通常用于把 Kotlin 源码与 Java 源码分开放置,但它不是所有 Android 项目都必须存在的固定目录。判断时应先确认它属于哪个 source set,再确认当前构建工具链是否会把该目录纳入编译。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
app/src/main/kotlin/ 中存在 .kt 文件 |
主 source set 单独存放 Kotlin 源码 | 确认这些文件能被当前模块正常编译 |
.kt 文件位于 app/src/main/java/ |
Kotlin 与 Java 共用源码目录 | 属于常见布局,不必为了语言不同而迁移目录 |
src/test/kotlin/、src/androidTest/kotlin/ 等目录存在 |
Kotlin 文件属于测试或其他 source set | 按对应 source set 排查依赖和编译问题 |
| IDE 能看到文件但编译找不到类 | 目录可能未进入实际编译源集 | 检查模块构建配置和 Kotlin、AGP 的目录约定 |
快速确认
在项目根目录列出模块中的 Kotlin 与 Java 源文件:
find app/src -type f \( -name '*.kt' -o -name '*.java' \) | sort预期输出:能够看到源码实际所在的 source set 和目录;路径随项目不同而变化,例如:
app/src/main/java/<PATH>.kt
app/src/test/kotlin/<PATH>.kt如果输出完全没有 kotlin 目录,并不代表项目配置错误,只说明当前项目没有采用这种目录布局。
出现条件与构建关系
Android 构建关注的是 source set 中哪些目录属于源码输入,而不是单纯看到一个名为 kotlin 的文件夹就自动编译其中内容。不同 Kotlin、Android Gradle Plugin 版本和项目配置对源码目录的约定可能不同,因此不要仅凭目录名称判断其是否生效。
很多 Android 项目直接把 .kt 与 .java 文件共同放在 src/main/java/。如果新建 src/main/kotlin/ 后代码无法解析,应先检查模块的 build.gradle 或 build.gradle.kts 以及当前工具链约定,而不是继续移动包目录。
建议动作与适用范围
查看项目结构时,先确定 main、test、androidTest、debug 等 source set,再判断其中源码目录的用途。遇到“文件存在但编译器找不到”的问题,应以 Gradle 实际编译输入为准。
本条适用于使用 Gradle 构建的 Android 项目。生成代码目录和第三方插件创建的源码目录可能采用其他路径,不应机械归入 kotlin 目录。
声明应用组件、权限、Intent Filter、主题和部分安全配置;检查 exported、权限、Deep Link 或组件注册问题时应优先查看。
AndroidManifest.xml
AndroidManifest.xml 是 Android 应用的清单文件,用于声明系统需要知道的组件、权限、Intent Filter 和应用级配置。排查组件无法启动、Deep Link 不匹配、权限缺失或 exported 配置问题时,应同时检查源码清单和最终合并后的 Manifest。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
<application> |
应用级主题、Application 类及组件容器 | 检查属性是否被其他 Manifest 合并结果覆盖 |
<activity>、<service>、<receiver>、<provider> |
向系统注册应用组件 | 组件无法解析时先确认名称和最终注册结果 |
<uses-permission> |
声明应用需要的系统权限 | 同时确认该权限是否还要求运行时授权 |
android:exported |
控制组件是否允许其他应用直接启动或调用 | 按组件用途显式设置,避免无意暴露 |
<intent-filter> |
声明组件能够响应的 Intent | 检查 action、category、scheme、host 和 path 是否匹配 |
主示例
下面是一份最小化的应用清单,声明网络权限以及可从桌面启动的 Activity:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.INTERNET" />
<application android:theme="@style/Theme.Example">
<activity
android:name=".MainActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>生效行为:系统能够识别 MainActivity 的启动器 Intent Filter;android:exported="true" 允许该入口由应用外部启动;INTERNET 权限进入最终应用清单。
快速验证
对于存在 debug 变体的常规 app 模块,可以执行 Manifest 处理任务验证清单能够完成合并:
./gradlew :app:processDebugMainManifest预期输出:任务成功时 Gradle 最终显示类似结果,实际耗时可能不同:
BUILD SUCCESSFUL in <TIME>如果项目没有 debug 变体或模块名不是 app,应改用实际模块和变体对应的任务。
合并结果为什么更重要
最终打包的 Manifest 可能同时来自 src/main、构建类型、Product Flavor 和依赖库,因此源码中的一份 AndroidManifest.xml 不一定等于最终结果。出现组件属性与预期不一致时,应检查 Manifest 合并结果,确认究竟是哪一份声明提供或覆盖了该属性。
常见问题与处理
面向 Android 12 及以上并以 API 31 或更高版本为目标时,带有 Intent Filter 的 Activity、Service 或 BroadcastReceiver 需要显式声明 android:exported。值应根据组件是否确实需要被其他应用访问来决定,而不是统一设置为 true。
Deep Link 无法命中时,应逐项核对 Intent Filter 中的 scheme、host、path 和 category;组件无法启动时则优先检查组件类名以及最终合并清单。对于危险权限,即使 Manifest 已声明,运行时仍可能需要向用户请求授权。
具体可用属性、权限行为和 Manifest 合并规则会随 Android SDK、目标 API 与 Android Gradle Plugin 版本变化,排查时应以项目实际目标版本和最终合并结果为准。
分别为 debug、release 等构建类型提供覆盖源码或资源,可覆盖 main 中的同名内容;排查不同环境行为不一致时需要检查。
src/debug 与 src/release
src/debug 和 src/release 是 Android 模块按构建类型划分的 Source Set。构建 debug 变体时会组合 src/main 与 src/debug,构建 release 时则组合 src/main 与 src/release,因此它们适合放环境专属资源、Manifest 配置或源码。
怎么判读
| 位置 | 何时参与构建 | 与 main 的关系 |
排查重点 |
|---|---|---|---|
src/main/ |
所有常规变体 | 提供公共内容 | 公共实现是否本身就有问题 |
src/debug/ |
debug 构建类型 | 可提供 debug 专属内容 | 调试地址、日志开关、资源覆盖 |
src/release/ |
release 构建类型 | 可提供 release 专属内容 | 正式地址、正式资源、安全配置 |
资源和 Manifest 会按 Source Set 规则合并,同名资源可以由更具体的 Source Set 覆盖。Java/Kotlin 源码则不能理解成简单的“同名文件覆盖”:如果同一变体最终同时编译两个具有相同完全限定类名的定义,通常会产生重复类或重复声明错误。
主示例
下面是片段示例:src/main 定义默认应用名称,src/debug 只覆盖同一个资源键。release 未提供覆盖时会继续使用 main 的值。
<!-- src/main/res/values/strings.xml -->
<resources>
<string name="app_name">Example</string>
</resources>
<!-- src/debug/res/values/strings.xml -->
<resources>
<string name="app_name">Example Debug</string>
</resources>构建 debug 资源以确认合并结果能够通过资源处理:
./gradlew :app:processDebugResources预期输出:任务成功结束,实际耗时和中间任务状态可能不同。
BUILD SUCCESSFUL in <TIME>此时 debug 变体中的 @string/app_name 为 Example Debug;release 变体在没有对应覆盖时仍使用 Example。
排查不同变体行为
出现“debug 正常、release 异常”或反过来时,先确认当前实际构建的变体,再检查对应目录中是否存在同名资源、额外 Manifest 节点、专属配置文件或源码。不要只搜索 src/main,否则很容易漏掉真正生效的覆盖内容。
适用范围
这种目录约定适用于 Android Gradle Plugin 的标准 Source Set 模型。自定义构建类型通常也可使用 src/<buildType>/;项目同时使用 Product Flavor 时还可能出现 flavor 和具体 variant 的 Source Set,最终应以当前变体实际参与合并的目录为准。
界面与资源文件
保存由 Android 资源系统管理的布局、图片、字符串、主题等内容,并生成 R 引用;资源必须按 Android 规定的目录和命名方式组织。
res 目录
src/main/res 保存交给 Android 资源系统处理的内容。构建时这些资源会经过校验、合并并生成对应的 R 标识符,因此目录类型、文件名和限定符都必须符合 Android 的资源规则,不能把它当成普通静态文件目录任意组织。
常见目录怎么判读
| 目录 | 主要内容 | 常见引用方式 |
|---|---|---|
layout/ |
View XML 布局 | R.layout.activity_main |
drawable/ |
图片、矢量图、Shape 等 | R.drawable.background |
mipmap/ |
通常用于启动器图标 | R.mipmap.ic_launcher |
values/ |
字符串、颜色、尺寸、样式等值资源 | R.string.app_name、R.color.primary |
menu/ |
菜单 XML | R.menu.main_menu |
xml/ |
网络安全配置、FileProvider 路径等通用 XML 资源 | R.xml.network_security_config |
raw/ |
需要按资源 ID 读取的原始文件 | R.raw.sample |
font/ |
字体及字体族 XML | R.font.app_font |
目录名还可以带配置限定符,例如 values-zh-rCN、layout-land 和 drawable-hdpi。系统会根据设备配置选择最匹配的资源,而不是要求应用代码手动判断每一种设备环境。
主示例
下面的片段示例定义字符串资源,并在布局中通过资源名引用它。两个 XML 分别位于 res/values/strings.xml 与 res/layout/activity_main.xml。
<!-- res/values/strings.xml -->
<resources>
<string name="screen_title">项目结构示例</string>
</resources>
<!-- res/layout/activity_main.xml -->
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/screen_title" />
</FrameLayout>可运行资源处理任务检查目录、XML 和引用是否合法:
./gradlew :app:processDebugResources预期输出:资源编译和合并没有错误,任务最终成功;缓存状态和耗时可能不同。
BUILD SUCCESSFUL in <TIME>构建成功后,代码侧可通过 R.string.screen_title 和 R.layout.activity_main 引用这两个资源。
命名与目录边界
资源文件名通常使用小写字母、数字和下划线,例如 activity_main.xml、ic_search.xml。不要使用空格、大写字母或把连字符写进普通资源文件名;连字符主要用于 values-night、layout-land 这类目录限定符。
res 下面也不能随意增加业务层级。例如把图片放入 res/drawable/icons/home.png 并不会得到一个新的资源命名空间,应通过资源命名规则表达分类,或把不需要 Android 资源 ID 的文件放到更合适的位置。
常见失败线索
遇到 resource ... not found、AAPT2 编译失败或 R 中没有预期字段时,优先检查资源是否位于正确目录、名称是否合法、XML 是否能解析,以及限定符目录名是否符合规则。若编译本身仍有资源错误,不要通过手动导入 android.R 来掩盖问题,因为它引用的是系统资源而不是当前应用模块的资源。
适用范围
这些规则适用于 Android 的标准资源系统和 Android Gradle Plugin 项目。采用 Jetpack Compose 的模块仍常用 res 保存字符串、图片、颜色、字体等资源,只是纯 Compose 界面通常不需要 layout/ XML。
保存传统 View 系统使用的 XML 布局,如 Activity、Fragment 和列表项界面;纯 Jetpack Compose 项目可能很少使用该目录。
layout 目录
res/layout/ 保存 Android View 系统的 XML 布局资源。每个合法文件都会进入资源表,并可通过 R.layout.<资源名> 引用;使用 Jetpack Compose 直接声明界面的页面通常不需要对应 XML。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
res/layout/activity_main.xml |
默认布局资源 | 在 Activity 等位置通过 R.layout.activity_main 引用 |
res/layout/item_user.xml |
可复用的列表项或局部界面 | 由 RecyclerView Adapter、Binding 等按需加载 |
res/layout-land/ |
横屏限定版本 | 与同名默认布局配套,不要只提供限定版本 |
res/layout-sw600dp/ |
针对较大最小宽度的替代布局 | 保持资源名一致,让系统按设备配置选择 |
资源文件名必须采用小写字母、数字和下划线等 Android 资源命名规则。不同配置下的同名 XML 应表达同一类界面资源,而不是借限定目录存放无关页面。
典型内容
下面是一个完整的传统 View 布局资源,可保存为 app/src/main/res/layout/activity_main.xml:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="16dp">
<TextView
android:id="@+id/titleText"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Hello Android" />
</LinearLayout>生效行为:资源处理阶段会把 activity_main.xml 注册为 R.layout.activity_main。传统 Activity 可把它交给 setContentView(R.layout.activity_main),Fragment、RecyclerView 或 View Binding 也可以加载相应布局。
出现条件
项目采用 XML + View、View Binding 或 Data Binding 时,layout 通常是主要界面资源目录。纯 Compose 页面则直接由 Kotlin 的 @Composable 函数描述 UI,因此可以不存在 res/layout/;混合项目仍可能同时保留两种界面方式。
常见误用
不要把图片、颜色、字符串或任意 XML 都放进 layout。布局 XML 的根元素应是可用于构建 View 层级的视图、布局容器或 Android 支持的特殊布局标签;图形资源应放到 drawable,字符串与尺寸等值资源通常放在 values。
如果同一布局存在多个限定版本,应至少准备能覆盖默认设备配置的 res/layout/ 版本,否则在没有匹配限定条件的设备上可能出现资源查找问题。
适用范围
这是 Android Resources 资源目录约定,适用于使用 Android View 系统的应用模块。具体可用限定符和资源选择规则由 Android 资源系统决定;Compose 是否使用该目录取决于项目是否还需要 XML View、互操作组件或第三方 View。
保存位图、矢量图以及 Shape、Selector 等 Drawable XML;页面背景、状态图标和普通图片资源通常从这里引用。
drawable 目录
res/drawable/ 保存可作为 Android Drawable 使用的图形资源,包括位图、Vector Drawable,以及 shape、selector、layer-list 等 XML。编译后通常通过 R.drawable.<资源名> 或 @drawable/<资源名> 引用。
怎么判读
| 资源形式 | 常见用途 | 建议动作 |
|---|---|---|
| PNG、WebP 等位图 | 照片、插图、普通图片 | 根据缩放需求选择合适的密度目录或 drawable-nodpi |
| Vector Drawable | 图标和简单矢量图形 | 优先用于适合矢量表达的可缩放图标 |
shape XML |
圆角背景、描边、渐变 | 用 XML 描述几何外观,避免为简单形状制作位图 |
selector XML |
按按下、选中等状态切换 Drawable | 明确状态匹配顺序,默认项通常放在最后 |
layer-list XML |
多个 Drawable 叠加 | 用于组合背景、边框和装饰层 |
drawable-hdpi、drawable-xhdpi 等目录可提供密度相关版本;drawable-night 等限定目录可按设备配置提供替代资源。Android 会依据当前配置从同名候选资源中选择最匹配的一份。
典型内容
下面的 Shape Drawable 可保存为 app/src/main/res/drawable/bg_card.xml,作为普通 View 的背景使用:
<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
android:shape="rectangle">
<solid android:color="#FFFFFF" />
<corners android:radius="12dp" />
<stroke
android:width="1dp"
android:color="#DDDDDD" />
</shape>生效行为:资源处理后可通过 R.drawable.bg_card 引用,也可以在 View XML 中写 android:background="@drawable/bg_card"。修改圆角、填充色或描边后,所有引用该 Drawable 的位置会使用更新后的资源定义。
放哪里更合适
启动器图标通常由 Android Studio 模板生成在 mipmap-* 等目录,不应因为它也是图片就机械移入 drawable。颜色值和用于 ColorStateList 的颜色资源则应根据资源类型放在 values 或 color 等合适位置。
对于位图,还要区分是否需要密度缩放。放入带密度限定符的目录表示资源具有对应基准密度;确实希望系统不按屏幕密度自动缩放的图片,可考虑 drawable-nodpi,但不应把它当作所有图片的默认目录。
常见误用
不要用高分辨率 PNG 替代本可由简单 Shape 或 Vector 表达的资源,否则会增加包体并降低适配灵活性。反过来,复杂照片也不适合强行转换为 Vector Drawable。
Selector 中状态项按声明顺序匹配,过于宽泛的条件如果放在前面,可能使后续状态永远无法命中。排查状态图标异常时,应先检查各 item 的状态条件和默认项顺序。
适用范围
drawable 属于 Android 标准资源体系,View 与 Compose 都可能间接使用其中的资源。例如 Compose 可以加载 R.drawable 资源,因此采用 Compose 并不意味着该目录没有用途;实际组织方式仍应以资源类型、密度和设备配置差异为依据。
主要保存不同屏幕密度下的应用启动图标等 mipmap 资源;普通页面图片通常更适合放入 drawable,而不是全部塞进 mipmap。
mipmap 目录
res/mipmap* 主要用于应用启动图标等需要由系统或 Launcher 按设备配置选择的资源。普通页面插图、背景和组件图片通常仍放在 drawable*,不要把 mipmap 当成通用图片目录。
怎么判读
| 目录或引用 | 含义 | 建议动作 |
|---|---|---|
mipmap-mdpi、mipmap-xhdpi 等 |
按屏幕密度提供位图版本 | 为启动图标准备对应密度资源 |
mipmap-anydpi-v26 |
不依赖固定像素密度、且面向 API 26+ 的资源 | 常用于自适应启动图标 XML |
@mipmap/ic_launcher |
按资源名引用 mipmap 资源 | Manifest 中的应用图标通常这样引用 |
| 普通页面图片 | 与界面内容一起渲染的图像资源 | 优先考虑 drawable 或 drawable-* |
自适应图标示例
下面是 res/mipmap-anydpi-v26/ic_launcher.xml 的片段示例,前景和背景资源需已经存在:
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<!-- 系统负责裁切最终图标形状,应用只提供前景和背景层 -->
<background android:drawable="@color/ic_launcher_background" />
<foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>生效行为:Android 8.0(API 26)及以上设备可把该资源作为自适应图标处理;较低版本通常由其他 mipmap-* 目录中的兼容图标承担。应用清单中的 android:icon 应引用对应的 @mipmap/... 资源。
常见误用
把所有 PNG、WebP 都放进 mipmap 不会带来普遍的画质优势,反而会模糊资源职责。界面内使用的普通图像优先放在 drawable;只有启动图标或确实需要 mipmap 语义的资源再放入这里。
集中定义字符串、颜色、尺寸、样式和主题等值资源;需要修改 App 名称、主题属性或公共尺寸时通常从这里查找。
values 目录
res/values 集中保存字符串、颜色、尺寸、样式等可按名称引用的值资源。需要修改 App 名称、公共颜色、间距或样式时,通常先在这里查找,而不是把相同字面值散落在布局和代码中。
怎么判读
| 常见内容 | 引用形式 | 主要用途 |
|---|---|---|
<string> |
@string/app_name |
文本与可本地化字符串 |
<color> |
@color/brand_primary |
可复用颜色值 |
<dimen> |
@dimen/content_padding |
尺寸、间距和字号等 |
<style> |
@style/... |
样式和主题属性集合 |
strings.xml、colors.xml、dimens.xml 等文件名主要用于组织内容;真正决定资源类型的是 <resources> 内的元素标签和资源名称。
值资源示例
下面的片段可放在 res/values/common.xml 中;同一个 values 文件可以声明多种值资源:
<resources>
<!-- 公共值集中命名,布局和代码只引用资源名 -->
<string name="app_name">Demo</string>
<color name="brand_primary">#6750A4</color>
<dimen name="content_padding">16dp</dimen>
<style name="AppCard">
<item name="android:padding">@dimen/content_padding</item>
</style>
</resources>生效行为:资源编译后可通过 @string/app_name、@color/brand_primary、@dimen/content_padding 和 @style/AppCard 引用。若资源名重复且处于同一有效配置中,会产生资源合并或编译冲突,应保持名称职责明确。
配置限定目录
values 还可以通过目录限定符提供不同配置下的替代值。例如 values-night 可覆盖夜间模式颜色,values-zh-rCN 可提供简体中文资源,values-sw600dp 可针对较大可用宽度调整尺寸。运行时由 Android 资源系统根据设备配置选择最匹配的一组资源。
排查入口
修改 App 名称时重点搜索 @string/app_name;主题颜色异常时同时检查默认 values 与 values-night 等限定目录;尺寸只在部分设备异常时,再检查 values-sw<N>dp 等配置是否覆盖了默认值。