設定應用程式模組

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

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

設定應用程式 ID

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

應用程式 ID 是由模組 build.gradle 檔案中的 applicationId 屬性定義,如下所示:

Groovy

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

Kotlin

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

雖然應用程式 ID 的樣式類似於傳統 Java 或 Kotlin 套件名稱,但應用程式 ID 的命名規則比較嚴格:

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

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

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

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

注意:如果要使用 WebView,建議您在應用程式 ID 中使用套件名稱做為前置字串;否則可能會遇到問題 211768 中所述的問題。

變更測試用應用程式 ID

根據預設,建構工具會使用特定建構變數的應用程式 ID,在檢測設備測試 APK 中套用應用程式 ID,並加上 .test。舉例來說,com.example.myapp.free 建構變數的測試 APK 應用程式 ID 會是 com.example.myapp.free.test

雖然您可以在 defaultConfigproductFlavor 區塊中定義 testApplicationId 屬性,但並非必要變更應用程式 ID。

設定命名空間

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

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

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

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

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

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

變更命名空間

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

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

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

變更測試用命名空間

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

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

注意:請勿將 testNamespacenamespace 設為相同的值,否則會發生命名空間衝突的情況。

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