使用 fitsSystemWindows

這是最快的方法。在 XML 佈局中，對最外層的 FrameLayout 加入屬性：

XML

<FrameLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:fitsSystemWindows="true">
    </FrameLayout>

這會讓系統自動幫 FrameLayout 加上內邊距，避開狀態列與導覽列。

程式碼精確控制

如果你只需要頂部避開狀態列，或是想保留背景填滿全螢幕，建議在 Activity 中使用 ViewCompat 監聽器。

Kotlin

ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.your_frame_layout)) { view, insets ->
    val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
    // 根據需求設定 padding
    view.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
    insets
}

這段程式碼會抓取系統欄的高度。將它設為 FrameLayout 的 padding 後，內容就不會被遮擋。

暫時停用強制規範

如果你還沒準備好適應新規則，可以在 Android 15 (API 35) 的主題中加入這個屬性。但注意這只是過渡方案，未來版本可能失效。²

在 res/values-v35/themes.xml 加入：

XML

<item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>

這會讓 App 回到舊版的顯示邏輯，不再自動延伸到系統欄下方。

Handling Edge-to-Edge in Android 15

這段影片詳細解說了 Android 15 強制全螢幕的原理，並示範如何在 Compose 和傳統 XML 中正確處理系統內邊距。

前置準備

首先電腦要安裝 ADB 工具。如果你有下載 Android Studio，它通常已經在裡面。如果是單獨下載 SDK Platform-Tools，記得要把路徑加入系統環境變數。手機端要開啟開發者選項，並把 USB 偵錯打開。

連接裝置

安裝前先確認電腦有沒有抓到手機。

adb devices

如果畫面出現一串序號加上 device 字樣，代表連接成功。如果顯示 unauthorized，記得看手機螢幕點選允許偵錯。

安裝指令

最基本的安裝指令很簡單。

adb install 路徑/檔名.apk

如果電腦上有好幾個檔案，可以直接把 APK 檔案拖進終端機視窗，它會自動填入路徑。

常用的安裝參數

有時候檔案已經存在，或者需要特殊權限，可以加參數。

• 覆蓋安裝：adb install -r 檔名.apk (保留原本的應用程式資料)
• 降版安裝：adb install -d 檔名.apk (允許安裝比手機現有版本還舊的 APK)
• 授予所有權限：adb install -g 檔名.apk (安裝完自動開啟所有權限)

指定特定裝置安裝

如果你同時接了兩台以上的手機，要指定其中一台。

adb -s 裝置序號 install 檔名.apk

裝置序號可以用剛才的 adb devices 指令查到。

常見問題

如果安裝失敗，通常會回傳錯誤代碼。

• INSTALL_FAILED_ALREADY_EXISTS：手機裡已經有同樣的 App，請改用 -r 參數。
• INSTALL_FAILED_INSUFFICIENT_STORAGE：手機空間不夠。
• INSTALL_FAILED_UPDATE_INCOMPATIBLE：簽名不一致，通常要先手動移除手機舊版 App 才能裝。

如果你已經安裝了 Android Studio，ADB 執行檔通常會藏在 SDK 的資料夾裡面。路徑會根據你的作業系統而有所不同。

Windows 系統的路徑

在 Windows 上，預設的路徑通常在你的使用者資料夾下。

C:\Users\使用者名稱\AppData\Local\Android\Sdk\platform-tools

注意 AppData 是一個隱藏資料夾，你可能要在檔案總管開啟顯示隱藏項目才看得到。在這個資料夾裡，你會找到 adb.exe。

macOS 系統的路徑

在 Mac 上，路徑通常在資源庫裡面。

/Users/使用者名稱/Library/Android/sdk/platform-tools

你可以直接在終端機輸入這個路徑來執行 adb，或者把這個路徑加到你的 .zshrc 檔案中，之後輸入 adb 就不需要完整路徑。

在 Android Studio 介面查看

如果你不確定路徑，可以從 IDE 裡面直接看。

1. 打開 Android Studio。
2. 點選 Settings (或是 macOS 的 Settings/Preferences)。
3. 尋找 Appearance & Behavior。
4. 點開 System Settings 找到 Android SDK。
5. 視窗右上方會直接顯示 Android SDK Location，那個路徑底下的 platform-tools 就是目的地。

快速執行的方法

如果你懶得找路徑，可以直接用 Android Studio 內建的 Terminal 視窗。

它會自動幫你設定好環境變數。只要在 Android Studio 下方點開 Terminal，直接輸入 adb 就能使用，不需要自己輸入長長的路徑。

寫一段把這個路徑加入系統環境變數的指令

既然你想要把路徑加入系統環境變數，這樣以後在任何資料夾輸入 adb 都能直接執行。我幫你整理了 Windows 和 Mac 的快速設定方式。

Windows 設定方式

你可以透過 PowerShell 指令直接把路徑加進去。請記得把下面的路徑換成你電腦上實際的路徑。

PowerShell

$adbPath = "C:\Users\使用者名稱\AppData\Local\Android\Sdk\platform-tools"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";" + $adbPath, "User")

執行完後，請重新啟動你的 PowerShell 或 CMD 視窗，輸入 adb version 確認是否成功。

macOS 設定方式

Mac 通常使用 Zsh，你需要修改設定檔。

1. 在終端機輸入 nano ~/.zshrc。
2. 在檔案最下方加入這行：export PATH=$PATH:/Users/使用者名稱/Library/Android/sdk/platform-tools
3. 按下 Ctrl + O 存檔，Ctrl + X 離開。
4. 輸入 source ~/.zshrc 讓設定生效。

驗證設定

設定完成後，不管你在哪個資料夾，直接輸入這行。

adb devices

如果能正常列出裝置清單，就代表你成功了。之後要安裝 APK，只要切換到檔案所在的資料夾，輸入 adb install 檔名.apk 就可以了。

Error message:

adb.exe: failed to install app.apk: Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE: Existing package com.your.packagename signatures do not match newer version; ignoring!]

這個錯誤訊息代表手機裡已經裝了同一個 App，但是舊版跟新版的「簽名（Signatures）」不一樣。這通常發生在舊版是從 Google Play 下載，而新版是你自己開發或從網路下載的 APK，系統為了安全會禁止覆蓋。

解決方案

因為簽名不一致，-r 參數（強制覆蓋）在這種情況下會失效。唯一的辦法是先移除手機上的舊版本，再重新安裝。

步驟 1：解除安裝舊版

你不需要在手機上點選，可以直接用指令移除。請使用這個 App 的套件名稱（Package Name）。

adb uninstall com.your.packagename

步驟 2：重新安裝新版

移除成功後，再執行你原本的安裝指令。

adb install app.apk

注意事項

解除安裝會導致該 App 的所有資料（如帳號紀錄、暫存檔）被清除。如果你開發時常遇到這個問題，建議確認你的開發環境（例如 Android Studio）是否使用了固定的 Debug Key。

如果執行 adb uninstall 還是失敗，需要我幫你查其他的移除參數嗎？

使用 Gradle Wrapper 編譯

Gradle Wrapper 是一個腳本。它能確保專案在不同機器上使用相同的 Gradle 版本。打開終端機並切換到專案路徑，執行以下指令：

./gradlew assembleDebug

這個指令會編譯出一個用於測試的 Debug 版本 APK。如果你需要正式上架的版本，則改用：

./gradlew assembleRelease

執行成功後，產出的檔案通常會放在 app/build/outputs/apk/ 目錄下。你會在裡面看到 debug 或 release 資料夾，副檔名就是 .apk。

常用指令與路徑

如果你的環境是 Windows，指令要改成 gradlew.bat assembleDebug。在執行編譯前，建議先清理舊的暫存檔：

./gradlew clean assembleDebug

這樣可以避免舊的檔案影響新的編譯結果。如果你的專案有多個不同的 Product Flavors，你可以用 ./gradlew tasks 查看所有可用的編譯指令。

關於 AAB 格式

現在 Google Play 要求上架必須使用 .aab 格式。如果你是為了上架準備，指令會稍微不同：

./gradlew bundleRelease

這會產生 Android App Bundle 檔案。位置在 app/build/outputs/bundle/release/ 之下。這比傳統的 APK 能提供更小的下載體積。

如果修改了 keystore 的存放路徑，最直接的調整位置是在專案中的 build.gradle 檔案。通常這個檔案位於 app 目錄下。你需要找到 signingConfigs 區塊。

修改 build.gradle 設定

在 signingConfigs 裡面，有一個屬性叫做 storeFile。你需要把後面的路徑指向新的位置。如果路徑是相對路徑，它是以專案根目錄為基準。

android {
    signingConfigs {
        release {
            storeFile file('/新的路徑/my-release-key.jks')
            storePassword '你的密碼'
            keyAlias '你的別名'
            keyPassword '你的密碼'
        }
    }
}

建議把路徑寫成相對路徑。例如 file(‘../keystores/release.jks’)。這樣換一台電腦開發時，只要相對位置正確，就不會出錯。

使用 gradle.properties 管理

為了安全與方便，很多人會把路徑寫在 gradle.properties 檔案裡。這樣就不會把私密路徑寫死在程式碼。你可以打開 gradle.properties 調整變數值。

MYAPP_RELEASE_STORE_FILE=/新的路徑/my-release-key.jks

然後在 build.gradle 引用這個變數。改完後記得執行一次 ./gradlew clean。這能確保 Gradle 抓到最新的路徑設定。

檢查環境變數

有些團隊會把路徑放在系統環境變數。如果你的設定是透過 System.getenv 取得。那你就要去修改作業系統的環境設定。修改完後可能需要重啟終端機或 IDE 才會生效。

在 build.gradle 引用 gradle.properties 的變數很簡單。Gradle 會自動將 properties 檔案中的屬性載入。

引用變數的方式

假設你在 gradle.properties 設定了變數名為 MYAPP_RELEASE_STORE_FILE。在 app/build.gradle 裡，你可以直接像這樣寫：

android {
    signingConfigs {
        release {
            // 直接使用變數名稱即可
            storeFile file(MYAPP_RELEASE_STORE_FILE)
            storePassword MYAPP_RELEASE_STORE_PASSWORD
            keyAlias MYAPP_RELEASE_KEY_ALIAS
            keyPassword MYAPP_RELEASE_KEY_PASSWORD
        }
    }
}

使用專案屬性檢查

有時候為了保險，會建議使用 project.hasProperty 來檢查變數是否存在。這樣即使變數沒設定，編譯也不會直接噴錯。這在多人協作時很好用。

Gradle

storeFile file(project.hasProperty('MYAPP_RELEASE_STORE_FILE') ? MYAPP_RELEASE_STORE_FILE : "default_path.jks")

關於路徑的提醒

如果你在變數中寫的是相對路徑，它是相對於專案根目錄。如果你希望路徑更靈活，可以搭配 rootDir 變數來組合：

Gradle

storeFile file("${rootDir}/keystores/${MYAPP_RELEASE_STORE_FILE}")

這樣無論在哪個層級的 gradle 檔引用，路徑都不會跑掉。改完設定後，建議執行 ./gradlew assembleRelease 測試看看能不能成功讀取。

看到 unsigned 代表這個 APK 還沒有經過數位簽署。Android 系統出於安全考慮，不會允許安裝任何未簽署的 APK。這通常是因為你的編譯指令或設定沒有正確關聯到簽署設定。

檢查 build.gradle 的類型設定

在 build.gradle 中，你雖然定義了 signingConfigs，但還必須在 buildTypes 裡面告訴 Gradle，release 版本要使用哪一組簽署設定。

android {
    buildTypes {
        release {
            // 這一行是關鍵，必須手動指定
            signingConfig signingConfigs.release 
            
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

如果漏掉了 signingConfig signingConfigs.release 這行，Gradle 就會預設產生不帶簽署的 APK，檔名就會出現 unsigned。

檢查簽署內容是否完整

如果設定已經寫了，但產出還是 unsigned，請檢查 gradle.properties 或 signingConfigs 區塊中的資訊是否齊全。簽署需要這四個要素：

• storeFile: keystore 檔案的路徑。
• storePassword: 儲存庫的密碼。
• keyAlias: 密鑰的別名。
• keyPassword: 該密鑰的獨立密碼。

只要缺一個，Gradle 有時候會因為找不到資訊而跳過簽署步驟，直接產出 unsigned 版本。

清除快取重試

有時候是之前的編譯產物殘留，導致你看到的是舊檔案。調整完設定後，請務必先執行清理指令再編譯：

./gradlew clean assembleRelease

如果設定正確，生成的檔名應該會變成 app-release.apk。

你需要我幫你檢查 signingConfigs 和 buildTypes 的對應程式碼嗎？

error message:

gradlew clean assembleRelease

* What went wrong:
A problem occurred evaluating project ':app'.
> Could not get unknown property 'release' for SigningConfig container of type org.gradle.api.internal.FactoryNamedDomainObjectContainer.

這個錯誤訊息代表你在 buildTypes 裡面引用了一個還沒定義的 signingConfigs 名稱。Gradle 的執行順序是由上而下，如果你先在 buildTypes 寫了 signingConfig signingConfigs.release，但當時 release 這個設定還沒被建立，就會報錯。

調整 build.gradle 的順序

在 Gradle 腳本中，定義的順序非常重要。你必須確保 signingConfigs 區塊寫在 buildTypes 之前。請檢查你的 app/build.gradle 結構是否如下：

android {
    // 1. 先定義簽署設定
    signingConfigs {
        release {
            storeFile file(MYAPP_RELEASE_STORE_FILE)
            storePassword MYAPP_RELEASE_STORE_PASSWORD
            keyAlias MYAPP_RELEASE_KEY_ALIAS
            keyPassword MYAPP_RELEASE_KEY_PASSWORD
        }
    }

    buildTypes {
        release {
            // 2. 這裡才能引用上面定義好的 release
            signingConfig signingConfigs.release
            
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-bundle.txt'), 'proguard-rules.pro'
        }
    }
}

常見的命名陷阱

錯誤訊息提到的 Could not get unknown property 'release'，有時候是因為你在 signingConfigs 裡面把名稱取錯了。例如：

• 如果你在 signingConfigs 裡寫的是 myConfig { ... }。
• 那在 buildTypes 就必須寫 signingConfig signingConfigs.myConfig。

兩邊的名稱必須完全對應。請確認你的 signingConfigs 括號內確實有名為 release 的區塊。

暫時註解法排查

如果你想確認是不是路徑變數導致的問題，可以先試著在 buildTypes 裡把 signingConfig signingConfigs.release 這一行註解掉。如果編譯能過（雖然產出又是 unsigned），那就代表問題百分之百出在簽署區塊的定義。

修正順序後，再執行一次編譯試試看。

你需要我幫你看一下你目前 build.gradle 第 20 行附近的程式碼長什麼樣子嗎？

2.1.0 是許多新特性的試用期，而 2.2.0 則是將這些功能正式轉為穩定版，並加強了代碼規範的檢查。

核心功能差異

• 語法穩定化：在 2.1.0 還是預覽的功能，如 when 表達式中的 guard 條件（when (x) { is String if x.isNotEmpty() -> ... }）、非局部 break 與 continue、以及多個 $ 符號的字串模板，在 2.2.0 都變成了正式穩定版。
• 預設介面方法 (JVM)：2.2.0 改變了 JVM 上的編譯方式。現在介面中的預設方法會直接編譯成 Java 的 default 方法，不再產生額外的 DefaultImpls 類別，這讓 Kotlin 與 Java 的交互更自然，字節碼也更簡潔。
• 標準庫加強：2.2.0 正式引入了穩定的 Base64 和 HexFormat API，以後處理編碼就不需要再找第三方函式庫或依賴特定平台。
• 上下文參數 (Context Parameters)：2.2.0 引入了這個新功能的預覽版（取代舊的 context receivers），這對簡化依賴注入和提升代碼可讀性很有幫助。

Android 開發者的影響

• 更嚴格的檢查：2.2.0 把很多 2.1.0 裡的警告提升到了錯誤級別。例如，如果你在 type aliases 裡用了不該用的 reified 修飾符，2.1.0 只會提醒你，2.2.0 會直接報錯不讓你編譯。
• 記憶體優化：Kotlin/Native 在 2.2.0 針對 Apple 平台（iOS）有更細緻的記憶體分配管理，這對 KMP（Kotlin Multiplatform）專案很有感。
• 編譯器警告管理：2.2.0 提供了統一的 -Xwarning-level 選項，讓你能更方便地控制專案中警告的顯示方式。

總結與建議

如果你是新專案，直接上 2.2.0 比較好，因為它的標準庫更完整，語法也更穩定。

但如果是舊專案升級，從 2.1.0 升到 2.2.0 可能會遇到一些編譯報錯（因為 2.2.0 把一些舊的不良語法警告變成了錯誤），需要花點時間修正代碼。

想了解具體的 when guard 語法範例，或是如何使用新的 Base64 API 嗎？

when guard 語法範例

這是 Kotlin 2.2.0 中最實用的新功能之一。它讓你在匹配類型的同時，可以直接加上額外的判斷條件，不需要在裡面多寫一層 if。

Kotlin

// 2.2.0 的寫法
when (response) {
    is Success if response.data.isEmpty() -> println("成功但沒資料")
    is Success -> println("拿到資料了")
    is Error if response.code == 404 -> println("找不到頁面")
    else -> println("其他錯誤")
}

在 2.1.0 以前，你必須寫成 is Success -> if (response.data.isEmpty()) ...，程式碼層級會變得比較深。現在這樣寫更直覺，閱讀起來很像在讀英文句子。

Base64 API 範例

以前在 Android 裡處理 Base64，我們通常會用到 android.util.Base64。但這會導致你的程式碼綁死在 Android 平台上。2.2.0 把這個功能放進了 Kotlin 標準庫。

import kotlin.io.encoding.Base64
import kotlin.io.encoding.ExperimentalEncodingApi

@OptIn(ExperimentalEncodingApi::class)
fun testBase64() {
    val text = "Hello Kotlin 2.2"
    
    // 編碼
    val encoded = Base64.encode(text.encodeToByteArray())
    println(encoded)
    
    // 解碼
    val decodedBytes = Base64.decode(encoded)
    println(String(decodedBytes))
}

這對寫 KMP 跨平台專案的人來說是救星。你可以直接在 commonMain 資料夾裡寫編碼邏輯，不用再幫 iOS 和 Android 各自寫一套實作。

開發建議

如果你還在用 2.1.0，建議可以先在 build.gradle 試著改版號。如果出現很多紅色底線，通常是 2.2.0 對於語法規範變得更嚴格。

像是有些隱含的類型轉換或是不規範的泛型用法，2.2.0 都會要求你寫清楚。雖然修起來有點煩，但這能讓你的專案體質更健康，減少執行時期的閃退。

現在主流的替代方案是 Kotlin Coroutines 和 RxJava。

核心比較與評估

Kotlin Coroutines：現代開發的首選

如果你使用的是 Kotlin，這幾乎是不二之選。

它的優勢在於結構化並發（Structured Concurrency）。當你在 ViewModel 中使用 viewModelScope.launch 時，如果 ViewModel 銷毀，協程會自動取消。這直接解決了 AsyncTask 最頭痛的內存洩漏問題。

此外，它讓異步代碼看起來像同步代碼。你不需要寫回調，只需要在函數前加一個 suspend 關鍵字，就能在後台執行任務後直接更新 UI，邏輯非常直觀。

RxJava：強大的流式處理工具

RxJava 是一把沉重的重型武器。

如果你的應用需要處理非常複雜的數據流，例如：同時監聽傳感器、網絡狀態與用戶輸入，並將這三者實時組合處理，RxJava 的操作符（如 combineLatest 或 zip）會非常強大。

但在一般的開發場景中，RxJava 的維護成本較高。新人接手時，面對幾十行連在一起的操作符通常會感到崩潰。而且 RxJava 的錯誤處理比較瑣碎，一旦漏掉 onError，程序可能直接崩潰。

遷移建議

如果你是從 AsyncTask 遷移：

• 無腦選擇 Coroutines： 這是目前 Android 開發的標準。它能完美替代 doInBackground（對應 withContext(Dispatchers.IO)）和 onPostExecute（協程自動切回主線程）。
• 考慮團隊成本： 協程的上手時間通常只要幾天，而 RxJava 可能需要幾週甚至幾個月才能熟練應用。
• 庫的整合： 現在的 Retrofit、Room 等主流庫都已經原生支持 Coroutines，遷移阻力極小。

可以用 Runnable 搭配 Handler 改寫。
這在協程普及前是很常見的做法。
原理是自己管理執行緒切換。
Runnable 負責定義要做的任務。
Handler 負責跨執行緒溝通。

具體的執行方式

你需要先準備一個 ExecutorService 執行緒池。
把耗時工作放進 Runnable 裡面。
透過 executor.execute 丟到背景執行。
當資料處理完畢。
再利用 Handler 的 post 方法切換回主執行緒。
這樣就能安全地更新介面元件。

ExecutorService executor = Executors.newSingleThreadExecutor();
Handler handler = new Handler(Looper.getMainLooper());

executor.execute(new Runnable() {
    @Override
    public void run() {
        // 這裡跑背景任務
        final String data = "載入完成";

        handler.post(new Runnable() {
            @Override
            public void run() {
                // 這裡更新 UI
                textView.setText(data);
            }
        });
    }
});

優缺點評估

這種做法控制權最高。
適合不支援 Kotlin 的老舊專案。
但是程式碼會變得很碎。
也要特別注意記憶體洩漏問題。
建議將 Handler 宣告為靜態類別。
才不會意外持有 Activity 的引用。
如果是簡單的任務。
這比導入整個協程庫還要輕量。

可以再利用 WeakReference 來優化這段程式碼以防止記憶體洩漏.

可空類型與不可空類型

在定義變量時，Kotlin 默認所有類型都是不可空的。如果你嘗試給它賦值 null，編譯器會直接報錯。

如果你希望一個變量可以存放 null，必須在類型後面加上問號。例如 String 不能為空，而 String? 則代表可以存放字符串或 null。

這種機制讓潛在的崩潰問題在編譯階段就被抓出來，而不是等到用戶使用時才發生。

安全調用與強行轉換

當你有一個可空變量時，你不能直接調用它的方法。你有幾種處理方式：

1. 安全調用符 ?.：這是最常用的。如果變量是 null，調用會直接返回 null，而不會崩潰。
2. 非空斷言 !!：如果你百分之百確定變量不為空，可以用這個。但如果猜錯了，程序會立刻崩潰。這通常是不建議的做法。

Elvis 運算符 ?:

這個符號用來提供「默認值」。當左邊的表達式結果為 null 時，它會執行右邊的內容。

這在處理 UI 顯示時非常好用，比如 val name = user?.name ?: "匿名用戶"。如果用戶數據不存在，就會直接顯示默認稱呼。

類型轉換與檢查

Kotlin 會自動進行類型轉換（Smart Cast）。如果你已經用 if 檢查過變量不為空，在該代碼塊範圍內，你可以直接把它當成不可空類型來用，不需要再寫問號。

這讓代碼保持乾淨，同時又具備極高的安全性。這就像是在寫代碼前加了一層過濾網，過濾掉所有可能讓程序當機的空指針。

1. 前置作業：確保 Java 已安裝

Android Studio 需要 Java Development Kit (JDK) 才能運行。由於您之前決定使用 Java 21，請確保它已正確安裝並設定 JAVA_HOME。

java -version

確認： 輸出顯示 Java 21 或更高版本。

2. 解壓縮 Android Studio

建議將 Android Studio 安裝到 /opt 目錄下，這是 Linux 系統中用於安裝非標準套件的推薦位置。

步驟 A：移動與解壓縮

1. 移動檔案 (如果檔案在 Downloads 資料夾)：Bash
   # 假設檔案在您的 Downloads 資料夾中
cd ~/Downloads
# 將檔案移到一個更合適的位置
sudo mv android-studio-2025.2.2.7-linux.tar.gz /opt/
2. 進入 /opt 目錄：
   cd /opt/
3. 解壓縮檔案：
   # 使用 sudo 權限解壓縮
sudo tar -xvf android-studio-2025.2.2.7-linux.tar.gz
   解壓縮後，會生成一個名為 android-studio 或類似名稱的資料夾。

3. 啟動 Android Studio

步驟 A：運行啟動腳本

進入解壓縮後的 bin 資料夾，並執行啟動腳本。

# 進入 bin 目錄 (請根據您的實際資料夾名稱調整)
cd /opt/android-studio/bin 

# 執行 studio.sh 腳本
./studio.sh

步驟 B：設定精靈 (Setup Wizard)

當您首次啟動時，Android Studio 會引導您完成幾個設定步驟：

1. 匯入設定：選擇是否匯入舊版 Android Studio 的設定。
2. 安裝類型：選擇 Standard 即可。
3. UI 主題：選擇您喜歡的主題（例如 Light 或 Darcula）。
4. 下載組件：設定精靈會列出需要額外下載的組件，包括：
   • Android SDK
   • Android SDK Platform-Tools
   • Android Virtual Device (AVD)
5. 點擊 Finish，等待所有必要的組件下載並安裝完成。

4. 建立桌面捷徑 (可選，但強烈建議)

手動安裝時，您需要手動建立一個桌面捷徑（.desktop 檔案），以便您可以從應用程式選單中啟動 Android Studio。

• 在 Android Studio 介面中建立捷徑：
  • 啟動 Android Studio 後，在頂部菜單欄選擇 Configure (或 File > Settings > Appearance & Behavior > System Settings > Menus and Toolbars，舊版在 Help)。
  • 選擇 Create Desktop Entry…。
  • 勾選 For all users (如果需要) 並點擊 OK。
    

• 手動建立捷徑 (如果步驟 1 失敗)：

# 創建一個 .desktop 檔案
nano ~/.local/share/applications/jetbrains-studio.desktop

# 貼入以下內容 (請確保 Exec 和 Icon 路徑正確)
[Desktop Entry]
Version=1.0
Type=Application
Name=Android Studio
Icon=/opt/android-studio/bin/studio.png # 圖標路徑
Exec="/opt/android-studio/bin/studio.sh" %f # 執行路徑
Comment=The official IDE for Android application development
Categories=Development;IDE;
Terminal=false
StartupWMClass=jetbrains-android-studio

5. 安裝 Android NDK (用於編譯 ics-openvpn)

您最終的目標是編譯 ics-openvpn，這涉及到 C/C++ 的本地程式碼，因此您必須安裝 Android NDK (Native Development Kit)。

1. 在 Android Studio 啟動後，開啟或創建一個專案。
2. 進入頂部菜單：Settings (或 File > Settings)。
3. 導航到：Appearance & Behavior > System Settings > Android SDK。
4. 切換到 SDK Tools 標籤頁。
5. 勾選 Android NDK (Side by side)。
6. 點擊 Apply，讓 Android Studio 下載並安裝 NDK。

完成這些步驟後，您的 Ubuntu 環境就具備了完整的 Android Studio 。

您遇到的錯誤訊息：

“Starting in Kotlin 2.0, the Compose Compiler Gradle plugin is required when compose is enabled.”

這表示編譯器誤以為您的專案正在使用 Jetpack Compose (Android 的現代 UI 工具包)，但缺少了 Compose Compiler 插件。

google 官方文件:
https://developer.android.com/develop/ui/compose/compiler?hl=zh-tw

有看沒有懂…

解決方案：檢查並新增 Kotlin 支援

解決這個問題的關鍵是確保您的專案正確地配置了 Kotlin Android Plugin 和 Kotlin Standard Library。

步驟 1: 檢查 Project-level 的 build.gradle (或 settings.gradle.kts)

確保您的專案級別 (Project-level) 的設定檔案中，已經加入了 Kotlin Gradle Plugin 的 Classpath。

在 build.gradle (Project 級別):

buildscript {
    ext.kotlin_version = '1.9.22' // 根據您的專案需求使用最新或穩定版本
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // ... 其他 dependencies
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" // <--- 確保有這行
    }
}

• 注意： 如果您使用的是新的 Gradle 設定方式 (Kotlin DSL)，則應在 settings.gradle.kts 中確保有這個 Plugin。

步驟 2: 編輯 Module-level 的 build.gradle (通常是 app/build.gradle)

這是最重要的步驟，您必須在編寫 Kotlin 程式碼的模組 (Module) 中應用 (apply) Kotlin 插件並新增必要的相依性。

在 app/build.gradle (Module 級別):

1. 套用 Plugin (Apply Plugin): 在檔案頂部，新增 kotlin-android 插件。 // 確保這裡有這兩行 plugins { id 'com.android.application' id 'org.jetbrains.kotlin.android' // <--- 確保有這行 // 如果您的專案是純 Java 且您剛剛加入 kotlin 檔案，您可能會需要將： // apply plugin: 'com.android.application' // 改為新的 `plugins` 區塊並加入 'org.jetbrains.kotlin.android' }
2. 新增 Kotlin 標準庫 (Standard Library): 在 dependencies 區塊中，新增 Kotlin 標準庫。 dependencies { // ... 其他 dependencies// 新增 Kotlin 標準庫相依性 implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" // <--- 確保有這行 // 如果您使用 Kotlin 與 Activity 或 Fragment 交互，建議也加入 KTX implementation "androidx.core:core-ktx:1.12.0" // 確保您使用的版本是最新的}

步驟 3: 移除或禁用 Compose 相關設定 (如果沒有使用 Compose)

如果您的專案確定沒有使用 Jetpack Compose，但錯誤訊息仍然出現，這可能是因為您在 app/build.gradle 中意外啟用了 Compose 設定。

請檢查 android 區塊：

• 尋找以下設定，如果存在且您沒有使用 Compose，請將其移除或註解掉：
  gradle android { // ... buildFeatures { // 這個可能會導致錯誤，如果專案沒有使用 Compose UI compose true // <--- 移除或改成 false } // ... }

最終動作

完成上述步驟後，請在 Android Studio 中點擊 Sync Now (或 Gradle 檔案修改後自動出現的同步提示)，讓 Gradle 下載並應用新的設定。這樣應該就能解決編譯器報錯，並允許 Java 程式碼正確地與您的 .kt 檔案（例如 BaseActivity.kt）互動。

核心原因分析

1. useLegacyPackaging = false 的作用：這個設定告訴 Android 建置系統（AGP），不要把 APK 裡面的 .so 檔案解壓縮到手機的 /data/app/…/lib/ 目錄下。它會讓系統直接從 APK 包裡面讀取這些函式庫（為了節省手機空間）。這就是為什麼你用 adb ls 看到目錄是空的。
2. OpenVPN (ics-openvpn) 的運作方式：Cake-VPN（以及大多數基於 ics-openvpn 的專案）並不是像一般 App 那樣只用 System.loadLibrary。它實際上是把 libovpnexec.so 當作一個可執行檔 (Executable) 來跑。Java 程式碼會嘗試去執行類似這樣的指令：/data/app/…/lib/arm64/libovpnexec.so …。因為你設了 false，檔案不存在於那個路徑上，導致 java.io.IOException，程式崩潰。

解決方案

為了同時修復崩潰問題並通過 Google Play 的 16 KB Page Size 檢查，你需要採取兩步走的策略：

第一步：修復崩潰（改回 True）

你必須允許 Native Library 被解壓縮，因為這個 App 的架構依賴於實體檔案的存在。

修改 build.gradle：

Groovy

android {
    packaging {
        jniLibs {
            // 改回 true (或者直接刪除這段，因為預設通常是 true)
            // 這樣 Android 才會把 .so 檔解壓到 /data/app/.../lib 目錄
            useLegacyPackaging = true
        }
    }
    // ... 其他設定
}

做完這步，你的 App 就能正常啟動了，但可能還過不了 16 KB 檢查。接下來看第二步。

第二步：真正解決 16 KB 對齊問題 (Rebuild NDK)

既然我們必須解壓縮 .so 檔（useLegacyPackaging = true），那麼 Google Play 的要求就是：這些解壓縮出來的 ELF (.so) 檔案，其 Segment 必須是 16 KB 對齊的。

這代表你不能只改 build.gradle 的 packaging 設定，你需要重新編譯 C/C++ 原始碼，並加上 Linker flags。

請在你的 build.gradle (Module level) 加入以下設定，強制 NDK 使用 16KB 對齊：

android {
    defaultConfig {
        // ... 其他設定
        
        externalNativeBuild {
            cmake {
                // 這是關鍵：告訴 Linker 使用 16KB (16384 bytes) 的 Page Size
                cppFlags "-Wl,-z,max-page-size=16384"
                arguments "-DANDROID_STL=c++_shared"
            }
            // 如果你是用 ndk-build (Android.mk)，則需要用不同的參數，但大多數現在都用 cmake
        }

        ndk {
            abiFilters "arm64-v8a", "x86_64"
        }
    }
}

注意：

如果你的專案不是透過 CMake 編譯（例如直接引用 libs/ 資料夾下的預編譯 .so 檔），那麼你無法透過 Gradle 修改對齊。你必須找到這些 .so 檔的原始碼重新編譯，或者尋找已經支援 16KB Alignment 的第三方庫版本。

驗證方法

修改並重新 Build 出 APK 後，請使用 Android SDK 提供的工具 zipinfo 或 Linux 的 readelf 來檢查。

1. 解壓 APK，取出裡面的 .so 檔。
2. 在終端機執行：
   readelf -l libovpnexec.so | grep LOAD
3. 檢查輸出中的 Align 欄位。如果是 0x4000 (16384)，代表成功；如果是 0x1000 (4096)，代表失敗。

總結

1. 把 useLegacyPackaging 改回 true (讓 OpenVPN 找得到檔案)。
2. 在 externalNativeBuild 加入 -Wl,-z,max-page-size=16384 (讓編譯出來的檔案符合 Google 規範)。