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文件;如果该文件包含导出的声明,则生成两个.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 = // intensive computations
println(result)
result
} // value is computed upon the first usage如果出于某种原因需要及早初始化属性(在应用程序启动时初始化),请使用 @EagerInitialization 注解对其进行标记。
开发二进制文件的增量编译
Kotlin/JS 编译器提供了开发二进制文件的增量编译模式,以加快开发过程。 在该模式下,编译器会在模块级别缓存 compileDevelopmentExecutableKotlinJs Gradle 任务的结果。 在后续编译中,它会对未更改的源文件重用已缓存的编译结果,从而加快编译速度,尤其是在改动较小的情况下。
增量编译默认处于启用状态。要为开发二进制文件禁用增量编译,请将以下行添加到项目的 gradle.properties 或 local.properties 中:
# Default: true
kotlin.incremental.js.ir=false增量编译模式下的全新构建(clean build)通常会较慢,因为需要创建并填充缓存。
生产环境中成员名称的缩减
Kotlin/JS 编译器利用其掌握的关于 Kotlin 类和函数关系的内部信息来执行更高效的缩减(minification),缩短函数、属性和类的名称。这减小了最终打包应用程序的体积。
当你在生产模式下构建 Kotlin/JS 应用程序时,会自动应用此类缩减,并且该功能默认处于启用状态。要禁用成员名称缩减,请使用 -Xir-minimized-member-names 编译器选项:
kotlin {
js {
compilations.all {
compileTaskProvider.configure {
compilerOptions.freeCompilerArgs.add("-Xir-minimized-member-names=false")
}
}
}
}无效代码消除
无效代码消除 (DCE) 通过移除未使用的属性、函数和类,来减小生成的 JavaScript 代码体积。
未使用的声明可能会在以下情况下出现:
- 函数被内联并且从未被直接调用(除少数情况外通常都是如此)。
- 模块使用了共享库。如果没有 DCE,库中未使用的部分仍会包含在最终产物包中。 例如,Kotlin 标准库包含用于操作列表、数组、字符序列的函数,以及用于 DOM(文档对象模型)的适配器等。所有这些功能如果作为 JavaScript 文件将占用约 1.3 MB。而一个简单的 "Hello, world" 应用程序仅需要控制台例程,整个文件只有几千字节。
在 Kotlin/JS 编译器中,DCE 会自动处理:
DCE 在开发打包任务中被禁用,对应以下 Gradle 任务:
jsBrowserDevelopmentRunjsBrowserDevelopmentWebpackjsNodeDevelopmentRuncompileDevelopmentExecutableKotlinJscompileDevelopmentLibraryKotlinJs- 名称中包含 "development" 的其他 Gradle 任务
如果构建生产包,则会启用 DCE,对应以下 Gradle 任务:
jsBrowserProductionRunjsBrowserProductionWebpackcompileProductionExecutableKotlinJscompileProductionLibraryKotlinJs- 名称中包含 "production" 的其他 Gradle 任务
通过使用 @JsExport 注解,你可以指定希望 DCE 视为根节点的声明。
