設定應用程式模組

本頁說明模組層級 build.gradle.kts 檔案中的實用應用程式設定。除了概略說明 build.gradle.kts 檔案中的重要屬性，您也可以學習如何執行下列操作：

  • 變更不同建構設定的應用程式 ID。
  • 根據應用程式 ID 安全地調整命名空間。

設定應用程式 ID

每個 Android 應用程式都有專屬的應用程式 ID，樣式類似於 Java 或 Kotlin 套件名稱，例如「com.example.myapp」。這組 ID 可用於在裝置和 Google Play 商店中明確識別應用程式。

應用程式 ID 是由模組 build.gradle.kts 檔案中的 applicationId 屬性定義，如下所示。將 com.example.myapp 替換為應用程式 ID，即可更新 applicationId 的值：

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

Groovy

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

雖然應用程式 ID 看起來類似傳統的 Kotlin 或 Java 套件名稱，但應用程式 ID 的命名規則比較嚴格：

  • 必須包含至少兩個區隔 (一或多個點)。
  • 每個區隔的開頭都必須是英文字母。
  • 所有字元都必須為英數字元或底線 [a-zA-Z0-9_]。

您在 Android Studio 中建立新專案時，系統會自動將 applicationId 指派給您在設定期間所選的套件名稱。在技術上，您從此可以直接獨立切換使用這兩項屬性，但我們不建議這麼做。

以下是設定應用程式 ID 的建議做法：

  • 讓應用程式 ID 與命名空間相同。這兩項屬性的差異可能有點令人混淆，但只要兩者保持一致，您就不需要擔心。
  • 發布應用程式後，請勿變更應用程式 ID。如果您進行變更，Google Play 商店會將後續上傳資料視為新的應用程式。
  • 明確定義應用程式 ID。如果未使用 applicationId 屬性明確定義應用程式 ID，則 ID 會自動採用與命名空間相同的值。這表示變更命名空間也會變更應用程式 ID，這通常不是您想要的結果。

變更測試用應用程式 ID

根據預設，建構工具會使用指定建構變化版本的應用程式 ID，在檢測設備測試 APK 中套用應用程式 ID，後方加上 .test。舉例來說，com.example.myapp.free 建構變化版本的測試 APK 應用程式 ID 會是 com.example.myapp.free.test。

如要變更應用程式 ID (這應該並非必要)，您可以在 defaultConfig 或 productFlavor 區塊中定義 testApplicationId 屬性。

設定命名空間

每個 Android 模組都有一個命名空間，做為所產生 R 和 BuildConfig 類別的 Kotlin 或 Java 套件名稱。

命名空間是由模組 build.gradle.kts 檔案中的 namespace 屬性定義，如以下程式碼片段所示。namespace 一開始會設為您在建立專案時選擇的套件名稱。

Kotlin

android {
    namespace = "com.example.myapp"
    ...
}

Groovy

android {
    namespace "com.example.myapp"
    ...
}

將應用程式建構到最終的應用程式套件 (APK) 時，Android 建構工具會使用命名空間做為應用程式產生的 R 類別的命名空間，該類別的用途是存取應用程式資源。範例：在上述建構檔案中，R 類別是在 com.example.myapp.R 建立。

因此，您為 build.gradle.kts 檔案設定的 namespace 屬性名稱必須與專案的基本套件名稱相同，也就是您的活動和其他應用程式程式碼所在位置。專案中可以有其他子套件，但這些檔案必須使用 namespace 屬性的命名空間匯入 R 類別。

為了簡化工作流程，請讓命名空間與應用程式 ID 保持相同 (如同預設)。

變更命名空間

在大多數情況下，您應讓命名空間和應用程式 ID 保持相同 (如同預設)。不過，如果您打算重新整理程式碼，或是想要避免命名空間衝突，有時可能需要變更命名空間。

在這些情況下，無論應用程式 ID 為何，您都可以更新模組 build.gradle.kts 檔案中的 namespace 屬性，藉此變更命名空間。在開始之前，請確保已明確定義應用程式 ID，這樣變更命名空間並不會同時變更應用程式 ID。如要進一步瞭解命名空間對應用程式 ID 可能造成的影響，請參閱「設定應用程式 ID」。

如果 namespace 和 Gradle applicationId 的名稱不同，建構工具會在建構作業結束時，將應用程式 ID 複製到應用程式的最終資訊清單檔案中。因此，如果您在建構後檢查 AndroidManifest.xml 檔案，package 屬性已設為應用程式 ID。合併資訊清單的 package 屬性是 Google Play 商店和 Android 平台實際查詢，藉此識別應用程式的位置。

變更測試用命名空間

androidTest 和 test 來源集的預設命名空間為主要命名空間，而且會在結尾加上 .test。例如，如果 build.gradle 檔案中的 namespace 屬性為 com.example.myapp，則根據預設，測試命名空間為 com.example.myapp.test。如要變更要測試的命名空間，請使用 testNamespace 屬性，如以下程式碼片段所示：

Kotlin

android {
    namespace = "com.example.myapp"
    testNamespace = "com.example.mytestapp"
    ...
}

Groovy

android {
    namespace "com.example.myapp"
    testNamespace "com.example.mytestapp"
    ...
}

注意：請勿將 testNamespace 和 namespace 設為相同的值，否則會發生命名空間衝突的情況。

如要進一步瞭解如何測試，請參閱「在 Android 上測試應用程式」。