R8 / ProGuard
本頁說明 Koin 在程式碼壓縮與混淆 (R8 / ProGuard) 下的行為、Koin 為你保留了哪些內容,以及你需要在自己的應用程式中保留哪些內容。
TL;DR
- Koin 的核心解析在 R8 下是安全的。
get<T>()、inject<T>()以及*Of建置函式(singleOf、factoryOf、viewModelOf…)會在編譯期解析相依性——它們使用具體化型別 (reified types),且在 Android/JVM 上是以Class.getName()作為註冊表的鍵。這不會在執行期對你的建構函式使用反射,因此你不需要為了 Koin 特別保留 (keep) 你的定義、ViewModel 或其建構函式。 - Koin 在其 Android AAR(
koin-android、koin-core-viewmodel、koin-compose-viewmodel、koin-androidx-workmanager、koin-androidx-startup)中隨附了consumer-rules.pro,因此下列規則會自動套用——你通常不需要額外新增任何設定。 - 你仍然需要保留由其他機制透過反射載入的類別(請參閱下文)。
Koin 為你保留的內容(隨附的取用端規則)
這些 AAR 抑制了關於 Koin 內部的 R8 警告:
-dontwarn org.koin.**koin-androidx-startup 額外保留了在 AndroidManifest 中參照的 initializer。這些規則都不會保留你的應用程式類別——Koin 不需要保留它們。
你必須保留的內容
這些需求來自平台或程式庫,而非來自 Koin 的解析:
- 由
KoinFragmentFactory建立的 Fragment 是透過類別名稱具現化的。請保留你的 Fragment 子類別(它們通常已透過@Keep、版面配置參照或 AndroidX 規則保留)。 - WorkManager 的
ListenableWorker子類別 已由androidx.work自己的取用端規則保留。 - 針對行程終止 (Process death) 的已儲存狀態。
SavedStateHandle是由 AndroidX 的CreationExtras提供,而非由 Koin 提供。放入其中的值必須與其他已儲存狀態一樣在 R8 處理後依然保留——請保留你自己的@Parcelize/Serializable狀態類別:
# 範例 — 保留你自己的已儲存狀態承載資料
-keep class com.example.** implements android.os.Parcelable { *; }ViewModel 與 SavedStateHandle (#2044)
一個常見的誤解是:間歇性出現的 No definition found for SavedStateHandle 當機是由於 R8 剔除了 Koin 的 ViewModel 反射所致。事實並非如此——viewModelOf(::MyViewModel) 是在編譯期處理的,因此在你的 ViewModel 上加上 -keep 並不會改變 Koin 的解析行為。
SavedStateHandle 僅在 ViewModel 建立期間可用(它是從傳遞給 Factory 的 CreationExtras 所建置)。請直接在 ViewModel 建構函式中解析它——不要使用延遲載入或在建構完成之後才解析:
// ✅ 在建立期間解析
class MyViewModel(val handle: SavedStateHandle) : ViewModel()
// ❌ 稍後解析 — 此時 CreationExtras 已不存在
class MyViewModel(koin: Koin) : ViewModel() {
val handle by lazy { koin.get<SavedStateHandle>() } // 會失敗
}如果你在 viewModelScope { } 內部宣告 ViewModel,請啟用對應的選項,以便建立該作用域:
startKoin {
options(viewModelScopeFactory())
modules(appModule)
}非 Android 目標 (JS / WASM / Native)
在 Android/JVM 上,Koin 以 Class.getName() 作為註冊表的鍵,這在 R8 處理下是穩定的。在 Kotlin/JS、WASM 和 Native 上,Koin 則使用來自 Kotlin 反射的 qualifiedName / simpleName。在這些目標上進行積極的名稱縮減 (minification) 可能會影響型別識別——當你在縮減非 Android 目標時,建議使用具名限定詞 (named("...")),而非依賴類別名稱。
