建構並執行應用程式

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

本總覽的重點在於如何使用 Android Studio 建構及執行應用程式，目的是進行測試和偵錯。如要瞭解如何使用 Android Studio 建構可向使用者發布的應用程式，請參閱「建構向使用者發布的應用程式」一文。如要進一步瞭解如何在使用或不使用 Android Studio 的情況下管理及自訂建構作業，請參閱「建構設定」一文。

基本建構與執行

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

在工具列中，從執行設定選單中選取您的應用程式。
在目標裝置選單中，選取要執行應用程式的裝置。

如果您未設定任何裝置，就必須建立 Android 虛擬裝置來使用 Android Emulator，或者連接實體裝置。
按一下「Run」圖示。

如果裝置出現相關錯誤或警告，當您試圖啟動專案時，Android Studio 會顯示警告。針對圖像和樣式變更，系統會區分「錯誤」(所選裝置造成設定無效) 和「警告」(所選裝置可能導致非預期行為，但仍可執行)。

監控建構程序

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

「Sync」分頁：顯示 Gradle 為與專案檔案保持同步而執行的工作。如果您遇到同步處理錯誤，您可以像使用「Build Output」分頁一樣，在樹狀結構中選取元素，深入瞭解該項錯誤。
「Build Output」分頁：以樹狀結構形式顯示 Gradle 執行的工作，其中各個節點代表一個建構階段或一組工作依附元件。如果您收到建構時間或編譯時間錯誤，請檢查樹狀結構並選取某個元素來讀取錯誤輸出內容，如圖 2 所示。
圖 2. 檢查「Build Output」視窗，查看錯誤訊息。
「Build Analyzer」分頁：提供版本的建構效能分析資訊。詳情請參閱「藉助版本分析器排解建構效能的問題」一文。
「Restart」：選取後會為專案中所有模組產生中繼建構檔案，效果與您依序選取「Build」>「Make Project」一樣，。
篩選器：篩選出警告，工作，或已處理完畢的警告和工作。這樣在輸出內容中會比較容易找到問題。

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

如果建構過程發生錯誤，Gradle 可能會推薦指令列選項，協助您解決問題，例如 --stacktrace 或 --debug。如何搭配建構程序使用指令列選項：

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

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

進階建構與執行功能

Android Studio 預設的建構及執行應用程式方式，應足以測試簡單的應用程式。不過，您可以使用這些建構和執行功能處理更進階的用途：

如要在偵錯模式下部署應用程式，請按一下「Debug」圖示。在偵錯模式下執行應用程式，即可在程式碼中設定中斷點、在執行階段期間檢查變數及評估運算式，以及執行偵錯工具。詳情請參閱「為應用程式偵錯」一文。
如果您的應用程式規模較大且較複雜，請使用「Apply Changes」，而不是點選「Run」圖示。這樣就不必在每次部署變更時重新啟動應用程式，可為您節省時間。如要進一步瞭解套用變更功能，請參閱「透過套用變更逐步部署」一節。
如果您使用的是 Jetpack Compose，即時編輯這項實驗功能可讓您即時更新可組合項，不須重新點選「Run」圖示。這可讓您專注於編寫 UI 程式碼，盡量減少干擾。詳情請參閱「即時編輯功能 (實驗功能)」一節。
如果應用程式有多個建構變數或版本，您可以透過「Build Variants」工具視窗選擇要部署的建構變數。如要進一步瞭解如何執行特定建構變數，請參閱「變更建構變數」一節。
如要微調應用程式安裝、啟動和測試選項，您可以變更執行/偵錯設定。如要進一步瞭解如何建立自訂執行/偵錯設定，請參閱「建立執行/偵錯設定」一節。
我們建議您依據開發需求使用 Android Studio，但也可以透過指令列將應用程式部署至虛擬或實體裝置。詳情請參閱「透過指令列建構應用程式」一文。

透過套用變更逐步部署

在 Android Studio 3.5 以上版本中，套用變更功能可讓您將程式碼和資源變更推送到執行中的應用程式，無需重新啟動應用程式。在某些情況下，也無需重新啟動目前的活動。如要部署及執行小幅增量的變更，同時保留裝置目前的狀態，就能透過這項彈性功能控制應用程式的重新啟動範圍。

套用變更功能會使用 Android JVMTI 實作中的各項功能 (搭載 Android 8.0 (API 級別 26) 以上版本的裝置支援這些功能)。如要進一步瞭解套用變更的運作方式，請參閱「Android Studio Project Marble：套用變更」一文。

使用套用變更

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

「Apply Changes and Restart Activity」圖示：套用資源和程式碼變更時，嘗試重新啟動活動但不重新啟動應用程式。一般來說，如果您已修改方法主體中的程式碼或修改現有資源，就可以採用這個選項。

您也可以按下 Control + Alt + F10 鍵 (在 macOS 上為 Control + Command + Shift + R 鍵)，執行這項操作。

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

您也可以按下 Control + F10 鍵 (在 macOS 上為 Control + Command + R 鍵)，執行這項操作。

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

為套用變更啟用備用執行功能

當您點選「Apply Changes and Restart Activity」或「Apply Code Changes」後，Android Studio 會建構新的 APK 並判斷是否可套用變更。如果無法套用變更，且會導致套用變更功能失敗，Android Studio 會改為提示您點選「Run」圖示，再次執行應用程式。

如果不想在每次發生這種情形時收到這個提示，可將 Android Studio 設定為在無法套用變更時自動重新執行應用程式。如要啟用這項行為，請按照下列步驟操作：

開啟「Settings」或「Preferences」對話方塊：
- 在 Windows 或 Linux 上，從選單中依序選取「File」>「Settings」。
- 在 macOS 上，從選單中依序選取「Android Studio」>「Preferences」。
依序前往「Build, Execution, Deployment」>「Deployment」。
勾選相關核取方塊，為這一或兩項「套用變更」操作啟用自動備用執行功能。
按一下「OK」。

因平台而異

套用變更的部分功能會依附於特定 Android 平台版本。如要套用這類變更，應用程式必須部署至搭載該 Android 版本或以上的裝置。舉例來說，新增方法需要使用 Android 11 以上版本。

套用變更的限制

「套用變更」旨在加快應用程式部署程序。不過，其使用時機有一些限制。

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

您必須重新啟動應用程式，才能套用部分程式碼和資源變更，包括：

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

程式庫與外掛程式

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

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

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

舉例來說，Firebase Crashlytics 在每次建構過程中會使用不重複的建構 ID 更新應用程式資源，進而讓您無法使用「Apply Code Changes」圖示，因此您必須重新啟動應用程式的活動才能看到變更。只要停用這個行為，即可搭配偵錯版本使用「Apply Code Changes」和 Crashlytics。

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

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

如果您在使用套用變更功能時遇到任何其他問題，請回報錯誤。

即時編輯 (實驗功能)

「即時編輯」是 Android Studio Giraffe 初期測試版的實驗功能，可以即時更新模擬器和實體裝置中的可組合項。這項功能可在編寫與建構應用程式的過程中盡量減少切換畫面，讓您長時間專注於編寫程式碼而不受干擾。

即時編輯提供兩種模式：

手動：系統會在您使用 Control + S 鍵 (在 macOS 上為 Command + S 鍵) 手動儲存時套用程式碼變更。
自動：當您更新可組合函式後，系統會在裝置或模擬器中套用變更。

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

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

最佳工作流程如下：

設定讓應用程式順利執行。
盡可能使用即時編輯功能，除非您需要進行這項功能不支援的變更，例如在應用程式執行期間新增方法。
在完成不支援的變更後，按一下「Run」圖示即可重新啟動應用程式並繼續執行即時編輯功能。

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

開始使用即時編輯功能

如要開始使用這項功能，請按照下列步驟建立空白的 Compose Activity、為專案啟用即時編輯功能，並透過即時編輯功能進行變更。

設定新專案

在開始之前，請確認您已安裝最新初期測試版本的 Android Studio Giraffe，且實體裝置或模擬器的 API 級別為 30 以上。
開啟 Android Studio，並在「Welcome to Android Studio」對話方塊中選取「New Project」。如果您已開啟專案，只要依序前往「File」>「New」>「New Project」即可建立新專案。
針對「Phone and Tablet」選擇「Empty Compose Activity」範本，然後按一下「Next」。

圖 4. 可供選擇的範本。為即時編輯功能選擇「Empty Compose Activity」。
在「New Project」對話方塊中填妥以下必要資訊：名稱、套件名稱、儲存位置、SDK 最低需求版本，以及建構設定語言。

圖 5. 專案設定範例。
按一下「Finish」。

啟用即時編輯功能

前往設定啟用即時編輯功能。
- 在 Windows 或 Linux 上，依序前往「File」>「Settings」>「Editor」>「Live Edit」。
- On macOS 上，依序前往「Android Studio」>「Settings」>「Editor」>「Live Edit」。
從設定中選取「Live Edit」選項和要執行的模式。

在手動模式中，每當您使用 Control + S 鍵 (在 macOS 上為 Command + S 鍵) 手動儲存程式碼變更，系統就會套用這些變更；在自動模式中，當您變更程式碼，相關變更就會立即套用到裝置或模擬器中。

圖 6. 「Live Edit」設定。
在編輯器中開啟 MainActivity 檔案，這是應用程式的進入點。
按一下「Run」即可部署應用程式。
開啟即時編輯功能後，「Running Devices」工具視窗右上方會顯示「Up-to-date」綠色勾號：

進行變更並檢查變更結果

如果系統支援您在編輯器中所做的變更，虛擬/實體測試裝置會自動更新。

例如，將 MainActivity 中現有的 Greeting 方法修改為以下內容：

@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)
    )
}

您的變更會立即顯示在測試裝置上，如圖 7 所示。

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

圖 7. 使用即時編輯功能對 Greeting 方法進行變更後，測試裝置顯示的內容。

排解即時編輯功能問題

如果測試裝置上沒有顯示編輯內容，表示 Android Studio 可能無法更新這些內容。請檢查即時編輯指標是否顯示「Out Of Date」(如圖 8 所示)，這表示發生編譯錯誤。如要進一步瞭解該錯誤與解決方式建議，請按一下指標。

即時編輯功能過時的圖示

圖 8. 即時編輯狀態指標。

即時編輯的限制

目前的限制如下。

即時編輯僅適用於 Compose 1.3.0 以上版本。如果專案使用較舊的 Compose 版本，即時編輯會處於停用狀態。
即時編輯功能僅適用於 AGP 8.1 以上版本。如果專案使用較舊的 AGP 版本，即時編輯會處於停用狀態。
即時編輯功能僅適用於搭載 API 級別 30 以上的實體裝置或模擬器。
即時編輯功能僅支援編輯函式主體，也就是說您無法變更函式名稱或簽章、新增或移除函式，或是變更非函式欄位。
透過即時編輯功能修改過的類別可能會對效能產生負面影響。如要評估應用程式效能，請使用簡潔的發布子版本執行應用程式。
您必須進行完整的執行作業，才能讓偵錯工具對透過即時編輯功能修改過的類別執行偵錯。
假如您透過即時編輯功能編輯執行中的應用程式，可能會導致應用程式當機。如果發生這種情況，您可以使用「Run」按鈕重新部署應用程式。
即時編輯功能不會執行您在專案建構檔案中定義的任何位元碼操控設定，例如使用「Build」選單中的選項，或是點選「Build」或「Run」按鈕建構專案時，會套用的位元碼操控設定。
非可組合函式會在裝置或模擬器上即時更新，並觸發完整重組功能。完整重組功能可能不會叫用已更新的函式。如果是非可組合函式，您必須觸發更新後的函式或再次執行應用程式。
應用程式重新啟動後，系統不會一併恢復即時編輯功能，因此您必須再次執行應用程式。
即時編輯功能僅支援可進行偵錯的程序。
如果專案在建構設定中針對 kotlinOptions 底下的 moduleName 使用自訂值，就不適用即時編輯功能。
即時編輯功能不適用於多次部署作業。換句話說，您無法先部署至某部裝置，再部署至另一部裝置。即時編輯功能只會在已部署應用程式的最後一組裝置上啟用。
即時編輯功能支援多裝置部署作業 (可部署至多部裝置，但這些裝置必須透過點選「目標裝置」下拉式選單中的「選取多部裝置」建立)。不過，由於系統並未正式支援這項功能，因此可能發生問題。如果您遇到問題，請向我們回報。

即時編輯功能常見問題

即時編輯功能目前處於什麼狀態？
- Android Studio Giraffe 初期測試版本提供的即時編輯仍為實驗功能。如要開啟或關閉這項功能，請依序前往「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」。
在選單中依序選取「View」>「Tool Windows」>「Build Variants」。
按一下工具視窗列中的「Build Variants」分頁標籤。

如果專案沒有原生/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 依附於僅由 v1 提供的類別；如果選取 v2，IDE 就無法識別該類別，因而無法解析該類別名稱，並在 M1 模組的程式碼中顯示錯誤。

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

變更執行/偵錯設定

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

預設的執行/偵錯設定會建構 APK、啟動預設專案活動，並使用「Select Deployment Target」對話方塊選取目標裝置。如果預設設定不適用於您的專案或模組，您可以自訂執行/偵錯設定，甚至在專案、預設和模組層級建立新設定。

如要編輯執行/偵錯設定，請依序選取「Run」>「Edit Configurations」。詳情請參閱「建立及編輯執行/偵錯設定」一文。