設定應用程式模組

本頁說明模組層級 build.gradle 檔案中的實用應用程式設定,建議您進行切換。除了概略說明 build.gradle 檔案中的重要屬性,我們也會說明如何執行下列操作:

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

設定應用程式 ID

每個 Android 應用程式都有專屬的應用程式 ID,看起來像 Java 套件名稱,例如 com.example.myapp。這組 ID 可明確識別裝置和 Google Play 商店中的應用程式。發布應用程式後,請勿變更應用程式 ID。上傳應用程式時,應用程式 ID (和使用這組憑證簽署的憑證) 必須與最初相符發布:一旦您變更應用程式 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 套件名稱 (程式碼的「命名空間」),但應用程式 ID 的命名規則比較嚴格:

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

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

設定應用程式 ID 時,建議您採用以下做法:

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

注意事項:應用程式 ID 是直接連結至程式碼套件名稱;因此,部分 Android API 的方法和參數名稱中會提到「套件名稱」,但實際上卻是您的應用程式 ID。舉例來說,Context.getPackageName() 方法會傳回您的應用程式 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 套件名稱。

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

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 上測試應用程式」一文。