Android 根目录相关文件说明-平芜编程栈

打开 Android Studio 项目，第一层就是项目根目录，很多人只会点开 app 模块写代码，完全不知道外层文件作用，下面按「必懂核心」「构建配置」「Git&忽略」「缓存日志」分类讲清楚，同时附上 app 模块内部关键文件。

一、根目录第一层整体结构预览

项目名/ ├── .gradle/ Gradle 构建缓存目录（不用管） ├── .idea/ Android Studio 配置文件（IDE专属） ├── app/ 主应用模块（99%业务代码在这里） ├── build/ 整个项目构建输出产物（可删除） ├── gradle/ Gradle Wrapper 包装脚本，控制Gradle版本 ├── .gitignore Git忽略文件配置 ├── build.gradle.kts 【全局项目构建配置（根级）】 ├── gradle.properties 全局Gradle属性、开关、AndroidX配置 ├── gradlew / gradlew.bat 跨平台Gradle执行脚本（Mac/Windows） ├── local.properties 本地SDK路径、NDK路径（每个人电脑不一样） ├── settings.gradle.kts 项目模块注册入口，告诉Gradle有哪些子模块

二、逐个文件详细解释

1. settings.gradle.kts 【超级重要】

作用：告诉 Gradle 当前项目包含哪些子模块，是项目入口清单
默认内容：

pluginManagement{repositories{google()mavenCentral()}}dependencyResolutionManagement{repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)repositories{google()mavenCentral()}}// 注册app模块include(":app")

新增 library 组件化模块，必须在这里include(":xxx")，否则AS识别不到；
里面同时配置了依赖仓库地址（google、mavenCentral）。

2. 根目录 build.gradle.kts（项目全局构建）

只做一件事：全局声明 AGP、Kotlin 插件版本，所有子模块共用
典型内容：

plugins{id("com.android.application")version"9.3.0"applyfalseid("com.android.library")version"9.3.0"applyfalseid("org.jetbrains.kotlin.android")version"2.0.0"applyfalse}

apply false：只定义版本，不在根目录直接运行插件；
app 模块只需要直接引用插件，不用重复写版本，统一版本避免冲突。

3. gradle.properties 全局配置文件（高频修改）

整个项目全局开关、常量、编译参数都写这里
常用配置：

# 开启AndroidX、Jetifier兼容（新项目必开） android.useAndroidX=true android.enableJetifier=true # JVM内存、并行构建 org.gradle.jvmargs=-Xmx4g org.gradle.parallel=true # 全局版本常量，子模块直接引用 minSdkVersion=24 targetSdkVersion=36 compileSdkVersion=36

用途：

统一 minSdk、compileSdk，改一处全部模块生效；
开启构建加速、AndroidX、R类优化等开关。

4. local.properties 【本地环境配置，禁止提交Git】

记录当前电脑本地环境路径，每台电脑自动生成，内容不一样
示例：

sdk.dir=C\:\\Users\\xxx\\AppData\\Local\\Android\\Sdk ndk.dir=xxx

作用：告诉项目本机 Android SDK 安装在哪；
换电脑、换SDK路径会自动重新生成，不要手动修改，不要上传代码仓库。

5. gradle 文件夹（控制Gradle版本核心）

gradle/wrapper/ └── gradle-wrapper.properties

唯一核心文件：gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-all.zip

决定当前项目用哪个 Gradle 版本，也就是你上一问关心的多版本管理的源头。

6. gradlew / gradlew.bat 脚本文件

gradlew：Mac / Linux 终端执行构建脚本
gradlew.bat：Windows CMD/PowerShell 执行脚本

使用示例：

# Mac打包正式包./gradlew assembleRelease# Windowsgradlew.bat assembleRelease

强制建议：永远用这两个脚本构建，不要用系统全局gradle，避免版本错乱

7. .gitignore Git忽略文件

配置哪些文件不需要提交到代码仓库，模板内容：

# 构建产物 /build/ /.gradle/ # 本地环境文件 local.properties # IDE配置 .idea/caches # 日志、APK、签名文件 *.apk *.log

作用：防止每个人IDE缓存、编译产物、本地路径冲突提交上去。

8. .idea 文件夹（Android Studio IDE配置）

存放：代码格式化规则、运行配置、索引、模块配置、版本控制记录

只给AS用，Gradle构建不依赖；
可以加入git提交，团队统一代码风格；也可以忽略，不影响项目运行。

9. .gradle 文件夹

Gradle 构建过程缓存、依赖缓存、任务缓存

可以随时删除，下次构建自动重新生成；
体积很大，定期删除可清理C盘空间。

10. 根目录 build 文件夹

整个项目编译中间产物、依赖解压包
完全可删，清理构建异常第一操作：删除所有build文件夹重新Sync

三、顺带：app 模块内部关键文件（日常写代码最常用）

进入app/文件夹：

app/build.gradle.kts
单个模块构建配置：applicationId、minSdk、签名、依赖、buildTypes、混淆开启等，每天都要改。
app/src/main/AndroidManifest.xml
App清单文件：包名、权限、Activity注册、启动页、应用图标、组件声明，安卓系统识别App的入口。
app/src/main/javaJava/Kotlin 业务代码目录
app/src/main/res资源目录（布局layout、图片drawable、字符串strings、样式style）
app/proguard-rules.pro代码混淆规则文件