設定應用程式模組

本頁說明模組層級 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。

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

設定命名空間

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

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

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

將應用程式建構到最終應用程式套件 (APK) 時，Android 建構工具會使用命名空間進行以下兩項操作：

這個名稱會做為應用程式產生的 R.java 類別 (用於存取應用程式資源) 的命名空間。
範例：在上述建構檔案中，R 類別是在 com.example.myapp.R 建立。
他們會使用這個名稱來解析資訊清單檔案中宣告的任何相對類別名稱。
範例：在上述建構檔案中，宣告 <activity android:name=".MainActivity"> 的活動已解析為 com.example.myapp.MainActivity。

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

為了方便起見，我們也建議將命名空間與您的應用程式 ID 保持不變，因為根據預設。

變更命名空間

我們強烈建議您保持命名空間及應用程式 ID 的預設值相同。不過，如果您打算重新編寫程式碼，或是想要避免命名空間衝突，有時可能需要變更命名空間。在這些情況下，無論應用程式 ID 為何，您都可以更新模組 build.gradle 檔案中的 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 屬性，如以下程式碼片段所示：

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

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

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