Kotlin/JS 編譯器特性
Kotlin/JS 編譯器在產生 JavaScript 程式碼之前,會先將 Kotlin 程式碼轉換為中間表示(IR)。 這個中間步驟讓編譯器能夠針對效能、大小和開發速度最佳化輸出內容,並讓你能掌控產生的 JavaScript,例如目標 JavaScript 版本、模組系統、TypeScript 宣告檔以及輸出細微度。
設定目標 JavaScript 版本
Kotlin/JS 編譯器可以產生符合 ECMAScript 標準 ES5、ES2015 和 ES2020 版本的 JavaScript。 請選擇你的目標環境所支援的最新版本。 在 build.gradle.kts 檔案中設定 target 屬性。例如,將目標設定為 ES2020:
tasks.withType<KotlinJsCompile>().configureEach {
compilerOptions {
target = "es2020"
}
}關於各個目標可用的功能,請參閱設定 ECMAScript 目標。
設定模組系統
Kotlin/JS 編譯器可以為不同的模組系統產生程式碼,例如 UMD、CommonJS、AMD 和 ES 模組。 若要選擇目標模組系統,請在 build.gradle.kts 檔案中設定 moduleKind 編譯器選項:
tasks.withType<org.jetbrains.kotlin.gradle.targets.js.ir.KotlinJsIrLink> {
compilerOptions.moduleKind.set(org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS)
}關於支援的 moduleKind 值和詳細設定,請參閱 JavaScript 模組。
產生 TypeScript 宣告檔 (`d.ts`)
Kotlin/JS 編譯器可以從你的 Kotlin 程式碼產生 TypeScript 定義。這些定義為 JavaScript 工具和 IDE 中的程式碼補全與靜態分析提供型別資訊,讓 Kotlin API 在 JavaScript 和 TypeScript 專案中更易於使用。
若要產生定義檔,請使用 @JsExport 標註 Kotlin 宣告,並在 build.gradle.kts 檔案的 js {} 區塊中新增 generateTypeScriptDefinitions() 函式:
kotlin {
js {
binaries.executable()
browser {
}
generateTypeScriptDefinitions()
}
}編譯器會收集標有 @JsExport 的頂層宣告,並在 .d.ts 檔案中產生 TypeScript 定義。
如需更多詳細資訊,請參閱產生 TypeScript 宣告檔 (d.ts)。
設定輸出細微度
你可以選擇編譯器在專案中輸出 .js 檔案的方式:
- 個別模組 (Per module):為每個專案模組產生單獨的
.js檔案(預設)。 - 整個程式 (Whole program):為整個程式產生單一的
.js檔案。 - 個別檔案 (Per file):為每個 Kotlin 檔案產生一個
.js檔案,若該檔案包含匯出的宣告則產生兩個(適用於es2015和es2020目標 JavaScript 版本)。
若要變更細微度,請在 gradle.properties 檔案中設定 kotlin.js.ir.output.granularity 屬性:
# Default: per-module
kotlin.js.ir.output.granularity=whole-program關於設定詳細資訊(包含個別檔案的需求),請參閱設定輸出細微度。
頂層屬性的延遲初始化
為了提升應用程式的啟動效能,Kotlin/JS 編譯器會延遲初始化頂層屬性。如此一來,應用程式載入時不需要初始化其程式碼中使用的所有頂層屬性。它只會初始化啟動時所需的屬性;其他屬性則會在實際執行使用它們的程式碼時才接收其值。
val a = run {
val result = // 密集運算
println(result)
result
} // 僅在首次使用時計算數值若因某些原因需要急切初始化屬性(在應用程式啟動時),請使用 @EagerInitialization 註解進行標記。
開發二進位檔的累加編譯
Kotlin/JS 編譯器提供了開發二進位檔的累加編譯模式,以加快開發流程。 在此模式下,編譯器會在模組層級快取 compileDevelopmentExecutableKotlinJs Gradle 任務的結果。 在後續編譯期間,編譯器會針對未變更的原始碼檔案使用快取的編譯結果,從而加快編譯速度,在變更幅度較小時尤為明顯。
累加編譯預設已啟用。若要停用開發二進位檔的累加編譯,請將以下行新增至專案的 gradle.properties 或 local.properties:
# Default: true
kotlin.incremental.js.ir=false累加編譯模式下的全新組建通常較慢,因為需要建立並填入快取內容。
生產環境中成員名稱的縮小化
Kotlin/JS 編譯器會利用其關於 Kotlin 類別與函式之間關聯的內部資訊來套用更有效率的縮小化,縮短函式、屬性和類別的名稱。這能縮小最終打包應用程式的大小。
當你在生產環境 (production) 模式下組建 Kotlin/JS 應用程式時,會自動套用這種類型的縮小化,且預設已啟用。若要停用成員名稱縮小化,請使用 -Xir-minimized-member-names 編譯器選項:
kotlin {
js {
compilations.all {
compileTaskProvider.configure {
compilerOptions.freeCompilerArgs.add("-Xir-minimized-member-names=false")
}
}
}
}無效程式碼消除
無效程式碼消除 (Dead code elimination, DCE) 透過移除未使用的屬性、函式和類別,來縮小產生的 JavaScript 程式碼大小。
未使用的宣告可能出現在以下情況:
- 函式已內嵌且從未被直接呼叫(除了少數情況外通常都會發生)。
- 模組使用了共用程式庫。在沒有 DCE 的情況下,即使未使用該程式庫的部分內容,這些內容仍會包含在最終的打包成果中。 例如,Kotlin 標準程式庫包含用於操作清單、陣列、字元序列的函式,以及 DOM(文件物件模型)配接器等。所有這些功能作為 JavaScript 檔案將需要約 1.3 MB。而一個簡單的「Hello, world」應用程式只需要主控台常式,整個檔案僅有幾 KB。
在 Kotlin/JS 編譯器中,DCE 會自動處理:
DCE 在開發環境打包任務中處於停用狀態,對應於以下 Gradle 任務:
jsBrowserDevelopmentRunjsBrowserDevelopmentWebpackjsNodeDevelopmentRuncompileDevelopmentExecutableKotlinJscompileDevelopmentLibraryKotlinJs- 名稱中包含 "development" 的其他 Gradle 任務
如果你組建生產環境打包成品,DCE 則會啟用,對應於以下 Gradle 任務:
jsBrowserProductionRunjsBrowserProductionWebpackcompileProductionExecutableKotlinJscompileProductionLibraryKotlinJs- 名稱中包含 "production" 的其他 Gradle 任務
透過 @JsExport 註解,你可以指定希望 DCE 視為根節點的宣告。
