建構並執行應用程式

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

如要查看應用程式在裝置上的外觀和行為,您需要建構並執行應用程式。Android Studio 會設定新專案,您只要點按幾下滑鼠,就能將應用程式部署至虛擬或實體裝置。

本總覽的重點在於如何使用 Android Studio 建構及執行應用程式,以用於測試和偵錯。如要瞭解如何使用 Android Studio 建構應用程式,以便向使用者發布應用程式,請參閱「建構向使用者發布的應用程式」一文。如要進一步瞭解如何透過 Android Studio 管理及自訂版本,請參閱「建構設定」一文。

基本建構與執行

如要建構並執行應用程式,請按照下列步驟操作:

  1. 在工具列中,從執行設定下拉式選單選取您的應用程式。
  2. 在目標裝置下拉式選單中,選取要執行應用程式的裝置。

    目標裝置下拉式選單。

    如果您未設定任何裝置,就必須建立 Android 虛擬裝置,才能使用 Android Emulator連接實體裝置

  3. 按一下「Run」

如果您嘗試將專案啟動至有相關錯誤或警告的裝置,Android Studio 會顯示警告。圖示和樣式變更區分為「錯誤」(所選裝置會造成設定無效) 與「警告」(所選裝置可能導致意外行為,但仍可繼續執行)。

監控建構程序

如要查看建構程序相關詳細資料,請依序點選「View」>「Tool Windows」>「Build」,或者按一下工具列中的「Build」圖示 。該視窗會顯示 Gradle 為建構應用程式而執行的工作,如圖 1 所示。

圖 1. Android Studio 中的「Build output」視窗

  1. 「Build」分頁:以樹狀結構的形式顯示 Gradle 執行的工作,其中每個節點代表一個建構階段或一組工作依附元件。如果您收到建構時間或編譯時間錯誤,請檢查樹狀結構並選取某個元素來讀取錯誤輸出內容,如圖 2 所示。

    圖 2. 檢查「Build output」視窗,查看錯誤訊息

  2. 「Sync」分頁:顯示 Gradle 為與專案檔案保持同步而執行的工作。與「Build」分頁類似,如果您遇到同步處理錯誤,請在樹狀結構中選取元素,深入瞭解該項錯誤。
  3. 重新啟動:與依序選取「Build」>「Make Project」執行相同的動作,會為專案中所有模組產生中繼建構檔案。
  4. 切換檢視模式:可切換以樹狀結構圖顯示工作執行情形,或顯示 Gradle 產生的詳細文字輸出內容 (與在 Android Studio 3.0 以下版本的「Gradle Console」視窗 中顯示的輸出內容相同)。

如果您的建構變數採用變種版本,Gradle 也會叫用工作來建構這些變種版本。如要查看所有可用的建構工作清單,請依序點選「View」>「Tool Windows」>「Gradle」,或按一下工具視窗列中的「Gradle」圖示

如果建構過程發生錯誤,Gradle 可能會推薦某些指令列選項來解決問題,例如 --stacktrace--debug。如要搭配建構程序使用指令列選項:

  1. 開啟「Settings」 或「Preferences」 對話方塊:
    • 在 Windows 或 Linux 上,從選單列中依序選取「File」>「Settings」
    • 在 Mac OSX 上,從選單列中依序選取「Android Studio」>「Preferences」
  2. 依序前往「Build, Execution, Deployment」>「Compiler」
  3. 在「Command-line Options」旁邊的文字欄位中,輸入指令列選項。
  4. 按一下「OK」即可儲存並結束。

Gradle 會在您下次嘗試建構應用程式時套用這些指令列選項。

進階建構與執行功能

Android Studio 部署應用程式的預設方式 (如前一節所述) 應足以測試簡易的應用程式。如需更多進階用途,可以切換應用程式建構與執行方式的各種面向:

  • 按一下「Debug」圖示 ,在偵錯模式中部署應用程式。在偵錯模式中執行應用程式,即可在程式碼中設定中斷點、在執行階段期間檢查變數及評估運算式,以及執行偵錯工具。詳情請參閱「為應用程式偵錯」一文。

  • 如果您的應用程式規模較大且更複雜,使用「套用變更」而非按一下「執行」將為您節省時間,因為每次部署變更時,都不必重新啟動應用程式。如要進一步瞭解套用變更,請參閱本頁的透過套用變更逐步部署

  • 如果您使用的是 Compose,可以利用「即時編輯」即時更新可組合項,而無須重新點選「Run」。這樣的好處是,您可以專心編寫使用者介面程式碼,不必經常中斷作業。詳情請參閱本頁的「即時編輯」一節。

  • 如果您的應用程式有多個建構變數或版本,您可以透過建構變數工具視窗選擇要部署的建構變數。如要進一步瞭解如何執行特定建構變數,請參閱本頁的「變更建構變數」。

  • 如要微調應用程式安裝、啟動和測試選項,您可以變更執行/偵錯設定。執行/偵錯設定會指定要從 APK 或 Android App Bundle 部署應用程式,以及要執行的模組、要部署的套件、要啟動的活動、目標裝置、模擬器設定、Logcat 選項等等。如要進一步瞭解如何建立自訂執行/偵錯設定,請參閱建立執行/偵錯設定

  • 您應嘗試針對開發需求使用 Android Studio,但也可以透過指令列將應用程式部署至虛擬或實體裝置。詳情請參閱「透過指令列建構應用程式」。

透過套用變更逐步部署

在 Android Studio 3.5 以上版本中,套用變更功能可讓您將程式碼和資源變更推送到執行中的應用程式,無需重新啟動應用程式。在某些情況下,也無需重新啟動目前的活動。如要部署及執行小幅增量的變更,同時保留裝置目前的狀態,就能透過這項彈性功能控制應用程式的重新啟動範圍。套用變更功能會使用 Android JVMTI 實作中的各項功能 (搭載 Android 8.0 (API 級別 26) 以上版本的裝置支援這些功能)。如要進一步瞭解套用變更的運作方式,請參閱「Android Studio Project Marble:套用變更」一文。

相關規定

您必須符合下列條件,才能使用變更變更動作:

  • 您可使用偵錯建構變數來建構應用程式的 APK。
  • 將應用程式部署至搭載 Android 8.0 (API 級別 26) 以上版本的目標裝置或模擬器。

使用套用變更

如果您要將變更部署至相容裝置,請使用下列選項:

套用變更並重新啟動活動 套用變更並重新啟動活動圖示

嘗試重新啟動活動但不重新啟動應用程式,藉此套用資源和程式碼變更。一般來說,如果您已修改方法主體中的程式碼或修改現有資源,就可以使用這個選項。

您也可以按下 Ctrl+Alt+F10 (或 macOS 上的 Control+Shift+Command+R) 來執行這項操作。

套用代碼變更 套用程式碼變更圖示

會嘗試僅套用程式碼變更,而不重新啟動任何項目。一般來說,如果您已修改方法主體中的程式碼,但未修改任何資源,就可以使用這個選項。如果您已同時修改程式碼和資源,請改用「Apply Changes and Restart Activity」

您也可以按下 Ctrl+F10 (或 macOS 上的 Control+Command+R) 來執行這項操作。

Run 圖示跑步

部署所有變更並重新啟動應用程式。如果您無法透過「套用變更」選項套用您所做的變更,就可以使用這個選項。如要進一步瞭解哪些變更類型需要重新啟動應用程式,請參閱「套用變更的限制」一節。

為套用變更啟用執行備用廣告

點選「Apply Changes and Restart Activity」或「Apply Code Changes」後,Android Studio 會建構新的 APK 並判斷是否可套用變更。如果無法套用變更,導致套用變更失敗,Android Studio 會提示您再次執行 Run 圖示 應用程式。不過,如果您不想在每次發生這種情形時收到這個提示,可將 Android Studio 設定為在無法套用變更時自動重新執行應用程式。

如要啟用這項行為,請按照下列步驟操作:

  1. 開啟「Settings」或「Preferences」對話方塊:

    • 在 Windows 或 Linux 上,從選單列中依序選取「File」>「Settings」
    • 在 macOS 選單中,從選單列中依序選取「Android Studio」>「Preferences」
  2. 依序前往「Build, Execution, Deployment」>「Compiler」

  3. 選取核取方塊來為其中一個「套用變更」動作啟用自動執行備用廣告功能。

  4. 按一下「OK」

因平台而異

「套用變更」的某些功能取決於特定 Android 平台版本。如要套用這類變更,您的應用程式必須部署至執行該 Android 或以上版本的裝置。

變更類型 最低平台版本
新增方法 Android 11

套用變更的限制

「套用變更」旨在加快應用程式部署程序。不過,使用時機有一些限制。如果您在使用套用變更時遇到任何問題,請回報錯誤

需要重新啟動應用程式的程式碼變更

應用程式重新啟動後,才能套用某些程式碼和資源變更,包括:

  • 新增或移除欄位
  • 移除方法
  • 變更方法簽章
  • 變更方法或類別的修飾符
  • 變更類別沿用設定
  • 變更列舉中的值
  • 新增或移除資源
  • 變更應用程式資訊清單
  • 變更原生資料庫 (SO 檔案)
程式庫與外掛程式

有些程式庫和外掛程式會自動變更應用程式的資訊清單檔案或資訊清單中參照的資源。這些自動更新會干擾套用變更,原因如下:

  • 如果程式庫或外掛程式變更應用程式的資訊清單,您就無法使用「Apply Code Changes」圖示 套用程式碼變更圖示 或「Apply Changes and Restart Activity」圖示 套用變更並重新啟動活動圖示,而是必須重新啟動應用程式才能看到變更。
  • 如果程式庫或外掛程式變更應用程式的資源檔案,則無法使用「Apply Code Changes」圖示 套用程式碼變更圖示,而是必須使用「Apply Changes and Restart Activity」圖示 套用變更並重新啟動活動圖示 才能看到變更。

如要避免受到這些限制影響,您可以停用偵錯建構變數的所有自動更新。

舉例來說,Crashlytics 在每次建構過程中會使用不重複的建構 ID 來更新應用程式資源,進而讓您無法使用「Apply Code Changes」圖示 套用程式碼變更圖示,因此您必須重新啟動應用程式的活動才能看到變更。您可以停用這類行為,以便將「Apply Code Changes」與 Crashlytics 一起用來處理偵錯版本。

直接參照已安裝 APK 內容的程式碼

如果您的程式碼會直接參照裝置上安裝的應用程式 APK 內容,在您點選「Apply Code Changes」圖示 套用程式碼變更圖示 後,該程式碼可能當機或出現異常。發生這種行為的原因是,在點選「Apply Code Changes」後,裝置上的基礎 APK 在安裝期間會遭到替換。在這類情況下,您可以改為點選「Apply Changes and Restart Activity」圖示 套用變更並重新啟動活動圖示 或「Run」圖示 Run 圖示

即時編輯 (實驗功能)

「即時編輯」是 Android Studio Flamingo 初期測試版本中的實驗性功能,可以即時更新模擬器和實體裝置中的可組合項。只要使用這項功能,即可在編寫與建構應用程式的過程中盡量減少切換畫面,更長時間地專心編寫程式碼。「即時編輯」有手動和自動兩種模式。在手動模式中,系統會在您使用 Ctrl + S (在 macOS 上為 Command + S) 手動儲存時套用程式碼變更;在自動模式中,當您更新可組合函式,相關變更就會馬上套用到您的裝置或模擬器中。

「即時編輯」主要針對的是與使用者介面和使用者體驗相關的程式碼變更,不支援更新方法簽章、新增方法或變更類別階層等異動項目。詳情請參閱「限制」一節。

這項功能無法做為建構及執行應用程式或套用變更功能的替代方法。其主要用途是對 Compose 使用者介面開發過程中的建構、部署及疊代工作流程進行最佳化。

最佳工作流程如下:

  1. 設定讓應用程式順利執行。
  2. 盡可能使用即時編輯功能,除非您需要進行這項功能不支援的變更 (例如在應用程式執行期間新增方法)。
  3. 在完成不支援的變更後執行應用程式,即可恢復即時編輯功能。

GIF 圖片展示如何透過裝置使用即時編輯功能

圖 3. 在自動模式中,每當您做出「即時編輯」支援的變更,裝置或模擬器上執行的應用程式就會即時更新。

開始使用「即時編輯」

想要馬上使用這項功能嗎?請按照下列步驟建立空白的 Compose 活動、為專案啟用即時編輯功能,並透過即時編輯功能進行變更。

設定新專案
  1. 在開始之前,確認您已安裝最新初期測試版本的 Android Studio Electric Eel,且實體裝置或模擬器的 API 級別至少為 30。

  2. 開啟 Android Studio,並在「Welcome to Android Studio」彈出式視窗中選取「New Project」。如果您已開啟專案,只要依序前往「File」>「New」>「New Project」即可建立新專案。

  3. 針對「Phone and Tablet」,選擇「Empty Compose Activity」範本,然後按一下「Next」

    在 Android Studio 中選取範本 圖 4. 可供選擇的範本。為即時編輯功能選擇「Empty Compose Activity」

  4. 輸入以下內容,然後按一下「Finish」

    • Name (名稱):HelloWorld
    • Package name (套件名稱):com.example.helloworld
    • Save location (儲存位置):預設
    • Language (語言):Kotlin
    • Minimum SDK (最低 SDK):保留預設值

    在 Android Studio 中輸入步驟 4 的專案設定範例 圖 5. 專案設定範例。

啟用「即時編輯」
  1. 在 IDE 中前往設定,啟用即時編輯功能。

    • 在 Windows 或 Linux 上,依序前往「File」>「Settings」>「Editor」>「Live Edit」
    • 在 macOS 上,依序前往「Android Studio」>「Preferences」>「Editor」>「Live Edit」
  2. 選取「Live Edit」選項,然後在設定中選擇要執行的模式。在手動模式中,每當您使用 Ctrl + S (macOS 上為 Command + S) 手動儲存程式碼變更,系統就會套用這些變更;在自動模式中,當您變更程式碼,相關變更就會立即套用到您的裝置或模擬器中。

    Android Studio 設定中的「Live Edit」核取方塊使用者介面 圖 6. 從設定中選取「Live Edit」選項。

  3. 在編輯器中開啟 MainActivity 檔案,這是應用程式的進入點。

  4. 按一下「Run」圖示 使用者介面按鈕 來部署應用程式,然後在編輯器右上方按一下「Split」,即可開啟預覽畫面。

  5. 開啟即時編輯功能後,編輯器右上角應會顯示「Live Edit」的綠色勾號。

    即時編輯功能的綠色勾號使用者介面

進行變更並檢查變更結果

在編輯器中,將 MainActivity 中現有的 Greeting 方法變更為以下內容。您的變更會立即顯示,如圖 7 所示。

@Composable
fun Greeting(name: String) {
    Text(text = "Hello $name!",
        Modifier.padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}

套用至裝置的 Greeting 方法變更內容

圖 7. 使用即時編輯功能對上述 Greeting 方法進行的變更內容會立即顯示。

疑難排解

如果預覽窗格中沒有顯示編輯內容,表示 Android Studio 可能無法更新編輯內容。確認「Live Edit」使用者介面的指標是否顯示暫停圖示,這代表有編譯錯誤。

即時編輯狀態使用者介面

圖 8. 如要進一步瞭解該錯誤與解決錯誤的建議,請將游標懸停在使用者介面的「Live Edit: ON」上。

限制

目前的限制如下。

  • 在 Compose 1.2.0 以下版本中,「即時編輯」可能不支援錯誤處理與回報功能。強烈建議您使用 Compose 1.3.0 以上版本以獲得最佳體驗。
  • 「即時編輯」僅適用於搭載 API 級別 30 以上的實體裝置或模擬器。
  • 即時編輯功能僅支援編輯函式主體,也就是說您無法變更函式名稱或簽章、新增或移除函式,或是變更非函式欄位。
  • 透過即時編輯功能修改過的類別可能會對效能產生負面影響。如要評估應用程式效能,建議您使用簡潔的發布子版本執行應用程式。
  • 您必須進行完整的執行作業,才能讓偵錯工具對透過即時編輯功能修改過的類別執行偵錯。
  • 假如您透過即時編輯功能編輯執行中的應用程式,可能會導致應用程式當機。如果發生這種情況,您可以用「Run」使用者介面按鈕 按鈕重新部署應用程式。
  • 即時編輯功能不會執行您在專案建構檔案中定義的任何位元碼操控設定,例如使用「Build」選單中的選項、或點選「Build」或「Run」按鈕時,會在建構專案時套用的位元碼操控設定。
  • 非可組合函式會在裝置或模擬器上即時更新,並觸發完整重組功能。完整重組功能可能不會叫用已更新的函式。對於非可組合函式,則您必須觸發新更新的函式或再次執行應用程式。
  • 應用程式重新啟動後,系統不會一併恢復即時編輯功能,因此您必須再次執行應用程式。
  • 如果您的專案使用 Compose 1.2 以上版本,則只有首次變更指定檔案的程式碼時會重設組合,後續編輯操作並不會重設組合。

常見問題

  • 即時編輯功能目前處於什麼狀態?
    • Android Studio Electric Eel 初期測試版本提供的「即時編輯」仍為實驗性功能。如要開啟或關閉這項功能,請依序前往「File」>「Settings」>「Editor」>「Live Edit」。在 macOS 上則依序前往「Android Studio」>「Preferences」>「Editor」>「Live Edit」
  • 何時該使用即時編輯功能?
    • 當您要快速查看使用者體驗元素更新 (例如修飾符更新、動畫) 對整體應用程式體驗的影響時,就可以使用即時編輯功能。
  • 何時該避免使用即時編輯功能?
    • 即時編輯功能目前著重於與使用者介面和使用者體驗相關的程式碼變更,但不支援更新方法簽章、新增方法或變更類別階層等相關異動,因此請避免在這些情況下使用這項功能。詳情請參閱「限制」一節。
  • 何時該使用 Compose 預覽?
    • 開發個別可組合項時,就可以使用 Compose 預覽功能。預覽功能會以視覺化的方式呈現 Compose 元素,並能自動重新整理,以顯示程式碼變更的效果。此外,預覽功能也能讓您查看不同設定和狀態下的 UI 元素 (例如深色模式、語言代碼、字型大小)。

變更建構變數

根據預設,在點選「Run」後,Android Studio 會建構應用程式的偵錯版本,不過這只能在開發期間使用。

如要變更 Android Studio 使用的建構變數,請在選單列中依序選取「Build」>「Select Build Variant」。

如果專案沒有原生/C++ 程式碼,「Build Variants」面板會有兩個資料欄:「Module」和「Active Build Variant」。模組的「Active Build Variant」值會決定 IDE 部署至已連結裝置的建構變數,並且顯示在編輯器中。

圖 9. 「Build Variants」面板會為沒有原生/C++ 程式碼的專案提供兩個資料欄

如要切換建構變數,請針對模組按一下「Active Build Variant」儲存格,然後從清單欄位中選擇所需的變數。

如果專案具有原生/C++ 程式碼,「Build Variants」面板會包含三個資料欄:「Module」、「Active Build Variant」和「Active ABI」。模組的「Active Build Variant」值會決定 IDE 部署至裝置的建構變數,並且顯示在編輯器中。以原生模組來說,「Active ABI」值會決定編輯器使用的 ABI,但不會影響部署的內容。

圖 10. 「Build Variants」面板會為具有原生/C++ 程式碼的專案新增「Active ABI」

如要變更建構變數或 ABI,請按一下「Active Build Variant」或「Active ABI」資料欄的儲存格,然後從清單中選擇所需的變數或 ABI。在您變更選項之後,IDE 會自動同步處理專案。變更應用程式或資料庫模組的任一資料欄後,該變更會套用至所有相依資料列。

根據預設,新專案設定有兩個偵錯版本:偵錯和發布版本。您必須建立發布版本,為公開發布應用程式做好準備

如要建構應用程式的其他變化版本,且每個版本有不同的功能或裝置需求,您可以定義其他建構變數

Android Studio 的「Build Variants」對話方塊中的衝突

Android Studio 的「Build Variants」對話方塊可能會顯示錯誤訊息,指出建構變數之間的衝突,如下所示:

「Build Variant」視窗顯示變數衝突錯誤

這個錯誤並不代表 Gradle 有建構問題,只代表 Android Studio IDE 本身無法解析所選模組變化版本之間的符號。

舉例來說,如果您的模組 M1 依附於 M2 模組的 v1 變化版本,但 M2 已在 IDE 中選取 v2 變化版本,IDE 中就會有未解析的符號。假設 M1 依附於 Foo 類別,而該類別僅適用於 v1。如果選取 v2,IDE 將無法識別該類別也無法解析,且會在 M1 程式碼中顯示錯誤。

IDE 無法同時載入多個變化版本的程式碼,因此系統會顯示這些錯誤訊息。不過,就您應用程式的建構作業而言,在這個對話方塊中所選的變化版本不會受到任何影響,因為 Gradle 在建構應用程式時,使用的是 Gradle 建構作業方案中指定的原始碼,而非 IDE 目前載入的項目。

變更執行/偵錯設定

首次執行應用程式時,Android Studio 會使用預設的執行設定。執行設定會指定要從 APK 或 Android App Bundle 部署應用程式,以及要執行的模組、要部署的套件、要啟動的活動、目標裝置、模擬器設定、Logcat 選項等等。

預設的執行/偵錯設定會建構 APK、啟動預設專案活動,並使用「Select Deployment Target」對話方塊選取目標裝置。如果預設設定不適用於您的專案或模組,您可以自訂執行/偵錯設定,甚至在專案、預設和模組層級中建立新設定。如要編輯執行/偵錯設定,請依序選取「Run」>「Edit Configurations」。詳情請參閱「建立及編輯執行/偵錯設定」。