Android 專案結構深入解析

當你建立一個 Android 專案時，Android Studio 會生成許多檔案與目錄。理解這些檔案的用途對於開發至關重要。

在 Android 模式下，我們可以更清晰地看到歸納後的結構：

app (模組目錄)

這是你主要工作的目錄，包含了 App 的原始碼與資源。

manifests 目錄

這是 Android View 為了方便管理而顯示的虛擬目錄，實際在檔案系統中的位置是 app/src/main/AndroidManifest.xml。

• AndroidManifest.xml：這是 App 的「身分證」。
  • 宣告 App 的名稱、圖示 (Icon)、主題 (Theme)。
  • 列出所有的 Activities (頁面)、Services、Broadcast Receivers 等元件。
  • 宣告 App 需要的 權限 (Permissions)，例如網路存取、相機、定位等。

<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />

    <application ...>
        <activity android:name=".MainActivity" exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

kotlin+java 目錄

這裡存放所有的 Kotlin (與 Java) 原始碼檔案。通常會有三個子目錄：

1. com.example.myapp：主要的程式碼（MainActivity, Data Models, ViewModels 等）。
2. com.example.myapp (androidTest)：UI 測試 (Instrumented Test) 的程式碼，執行在模擬器或實機上。
3. com.example.myapp (test)：單元測試 (Unit Test) 的程式碼，執行在電腦的 JVM 上。

res (資源目錄)

這裡存放非程式碼的資源檔案。Android 會自動為這些資源生成 R 類別的 ID，方便在程式碼中引用（例如 R.string.app_name）。

• drawable/：圖片檔（PNG, JPEG, WebP）與向量圖（XML Vector Drawable）。
• layout/：傳統 XML 佈局檔（在 Compose 專案中較少用到，除非混用舊版 View 系統）。
• mipmap/：應用程式的啟動圖示 (App Icons)。通常有不同解析度的版本。
• values/：
  • colors.xml：定義顏色代碼。
  • strings.xml：定義文字字串。這對於多國語系 (Localization) 非常重要，你不應該在程式碼中寫死 (Hardcode) 文字。
  • themes.xml：定義 App 的全域樣式（主要用於傳統 View 系統或設定狀態列顏色等）。
• xml/：其他 XML 設定檔（例如網路安全性設定、捷徑設定）。

Gradle Scripts (建置腳本)

Android 使用 Gradle 作為建置系統。這裡通常有兩個主要的 build.gradle.kts 檔案：

build.gradle.kts (Project: My Application)

這是專案層級的設定檔，定義全域的設定，例如 Gradle Plugin 的版本。通常不需要頻繁修改。

// Project-level build.gradle.kts
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
}

build.gradle.kts (Module: app)

這是模組層級的設定檔，也是你最常修改的地方。

// Module-level build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.jetbrains.kotlin.android)
}

android {
    namespace = "com.example.myfirstapp"
    compileSdk = 34 // 編譯時使用的 SDK 版本

    defaultConfig {
        applicationId = "com.example.myfirstapp" // 上架時的唯一 ID
        minSdk = 24     // 最低支援版本
        targetSdk = 34  // 目標適配版本
        versionCode = 1 // 內部版本號 (整數)
        versionName = "1.0" //顯示版本號 (字串)
    }
    // ...
}

dependencies {
    // 這裡宣告第三方套件依賴
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.ui)
    implementation(libs.androidx.material3)
    // ...
}

libs.versions.toml (Version Catalog)

在較新的 Android Studio 專案中，你會看到 gradle/libs.versions.toml 檔案。這是 Gradle 的 Version Catalog 功能，用來集中管理依賴套件的版本。

這樣的好處是，如果你的專案有多個模組 (Modules)，它們可以共享同一個版本號設定，不用擔心版本衝突。

小結

• Manifest：權限與元件宣告。
• Java/Kotlin：邏輯程式碼。
• Res：圖片、字串資源。
• Gradle：依賴管理與建置設定。

了解這些結構後，你已經具備了解讀 Android 專案的基礎能力。接下來，我們將深入探討 Gradle 的運作細節。