20. 项目文件结构

两种视图

Android Studio 左侧项目视图有两种常用模式：

• Android 视图：按 Android 概念分组（manifests、java、res、Gradle Scripts），日常开发用这个，简洁。
• Project 视图：按磁盘真实结构显示，最完整，找原始文件用。

下面以 Project 视图 讲真实结构，因为 Android 视图是它的一种展示形式。

顶层结构

新建一个项目，磁盘上长这样：

MyFirstApp/
├── .gradle/                  Gradle 缓存（自动生成，别动）
├── .idea/                    IDE 配置（自动生成，别动）
├── app/                      应用模块（核心）
├── gradle/
│   ├── wrapper/              Gradle Wrapper
│   └── libs.versions.toml    Version Catalog（依赖版本）
├── build.gradle.kts          项目级构建脚本
├── settings.gradle.kts       项目设置
├── gradle.properties         Gradle 属性
├── gradlew / gradlew.bat     Gradle Wrapper 脚本
└── local.properties          本地 SDK 路径（不提交）

重点关注 app/、build.gradle.kts、settings.gradle.kts、gradle/libs.versions.toml 这几个。

app 模块

应用代码都在 app/ 模块里（模块名可以改，默认叫 app）：

app/
├── build.gradle.kts              模块级构建脚本
├── proguard-rules.pro            混淆规则
└── src/
    ├── main/
    │   ├── AndroidManifest.xml   应用清单
    │   ├── java/com/example/app/
    │   │   ├── MainActivity.kt
    │   │   └── ui/theme/...
    │   └── res/
    │       ├── drawable/
    │       ├── mipmap-*/
    │       ├── values/
    │       │   ├── strings.xml
    │       │   ├── colors.xml
    │       │   └── themes.xml
    │       └── xml/
    ├── test/                     单元测试（JVM）
    └── androidTest/              仪器化测试（设备上跑）

src/main/java

放 Kotlin/Java 源码，按包名分层。常见分包方式：

com/example/app/
├── MainActivity.kt
├── data/
│   ├── model/           数据模型
│   ├── repository/      数据仓库
│   └── remote/          网络层
├── ui/
│   ├── screen/          各个屏幕
│   ├── component/       复用组件
│   └── theme/           主题
└── util/                工具类

src/main/res

资源目录，第 23 章细讲。常用子目录：

目录	内容
values/	字符串（strings.xml）、颜色（colors.xml）、主题（themes.xml）、尺寸
drawable/	图片（PNG、JPG）、矢量图（XML）、形状（shape）
mipmap-mdpi ~ mipmap-xxxhdpi	应用图标，按密度分
layout/	XML 布局（传统 View 用，Compose 不用）
font/	字体
xml/	备份规则、数据提取规则等
raw/	原始文件（音频、视频、JSON）

src/test 和 src/androidTest

• src/test/：单元测试，跑在 JVM 上，不依赖 Android 框架（用 JUnit、MockK）。
• src/androidTest/：仪器化测试，跑在设备/模拟器上，能访问 Android API（用 Espresso、Compose Test）。

顶层 build.gradle.kts

项目级构建脚本，配置整个项目：

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.compose.compiler) apply false
}

apply false 表示这里声明但不应用，具体应用在模块级脚本里。新版本 Gradle 推荐这种写法，统一管理插件版本。

模块级 build.gradle.kts

模块级构建脚本，最重要的配置文件之一：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.compose.compiler)
}

android {
    namespace = "com.example.myfirstapp"   // R 类生成的包名
    compileSdk = 36                         // 编译 SDK 版本

    defaultConfig {
        applicationId = "com.example.myfirstapp"  // 应用唯一 ID
        minSdk = 24                                 // 最低支持
        targetSdk = 36                              // 目标版本
        versionCode = 1                             // 版本号（整数）
        versionName = "1.0"                         // 版本名（显示用）

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = true                  // 开启混淆
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    buildFeatures {
        compose = true                              // 启用 Compose
    }
}

dependencies {
    implementation(libs.androidx.core.ktx)
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.material3)
    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
}

关键字段：

• namespace：生成 R 类的包名，也是 Manifest 合并时的包名。
• applicationId：应用唯一标识，上架后不能改。
• compileSdk / minSdk / targetSdk：第 3 章讲过。
• versionCode / versionName：版本号，更新时递增。
• buildTypes：构建变体，release 默认开启混淆。
• dependencies：依赖声明。

• namespace 和 applicationId 可以不一样。namespace 是代码层面的包名，applicationId 是发布标识。一般保持一致，迁移老项目时可能不同。

settings.gradle.kts

项目级设置，声明包含哪些模块、用哪些仓库：

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "MyFirstApp"
include(":app")

• repositories 声明从哪下依赖。google() 是 Google 仓库（AndroidX、Compose），mavenCentral() 是 Maven 中央仓库。
• include(":app") 声明项目包含 app 模块。多模块项目这里加多个。

• 国内下载慢可以在 repositories 里加阿里云镜像：maven("https://maven.aliyun.com/repository/public") 和 google 的镜像。注意别提交到公共仓库。

gradle/libs.versions.toml

Version Catalog，统一管理所有依赖版本。新版 Android Studio 默认用这个：

[versions]
agp = "8.7.0"
kotlin = "2.0.21"
compose-bom = "2024.12.01"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "core" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version = "1.9.3" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

在 build.gradle.kts 里用 libs.androidx.core.ktx 引用，版本升级改 toml 一处即可，比散落各处好维护。

其他配置文件

gradle.properties

Gradle 和 Kotlin 的全局参数：

org.gradle.jvmargs=-Xmx2048m        # Gradle 用内存
android.useAndroidX=true             # 强制用 AndroidX
kotlin.code.style=official
org.gradle.caching=true
org.gradle.parallel=true             # 并行构建

local.properties

本地 SDK 路径，不提交到 Git：

sdk.dir=D:\\Android\\Sdk

proguard-rules.pro

混淆规则文件。开启混淆后，需要保留的类（反射用的、JNI 调的）在这里声明 -keep。

常见操作对应文件

想干什么	改哪个文件
加依赖	模块级 build.gradle.kts 的 dependencies
改最低支持版本	模块级 build.gradle.kts 的 minSdk
改应用名	res/values/strings.xml 的 app_name
改应用图标	res/mipmap-*/ic_launcher
注册新 Activity	AndroidManifest.xml
改包名	namespace + applicationId + 重构目录
加权限	AndroidManifest.xml
配签名	模块级 build.gradle.kts 的 signingConfigs

小结

项目顶层有 app/ 模块和几个 Gradle 配置文件。app/src/main/ 下分 java（代码）、res（资源）、AndroidManifest.xml（清单）。构建配置在 build.gradle.kts（项目级 + 模块级），依赖版本在 gradle/libs.versions.toml 统一管理，模块和仓库在 settings.gradle.kts。下一节深入 Gradle 构建系统。