Kotlin/JS

Kotlin/JS 可以把 Kotlin 代码、Kotlin 标准库以及兼容依赖转译为 JavaScript，让 Kotlin 应用运行在浏览器、Node.js、serverless 等 JavaScript 环境中。

适用场景

常见用途：

  • 前后端共享 DTO、校验规则、认证逻辑、API 抽象。
  • Android、iOS、Web 共享业务逻辑。
  • 使用 Kotlin 编写前端应用，例如 React wrapper、Kobweb、Kilua 等生态。
  • Node.js 或 serverless 场景。
  • Multiplatform 项目中的 Web 目标。
  • 需要支持较老浏览器时，作为 Kotlin/Wasm 之外的补充目标。

Java 对比：Java 本身主要运行在 JVM；Kotlin/JS 则把 Kotlin 编译到 JS 生态，让共享代码进入浏览器和 Node.js。

通过 Multiplatform Gradle 插件使用

官方建议通过 Kotlin Multiplatform Gradle plugin 配置 JS 目标：

plugins {
    kotlin("multiplatform") version "2.4.0"
}

kotlin {
    js {
        browser()
        nodejs()
    }
}

你可以只配置 browser，也可以只配置 nodejs。具体目标取决于运行环境。

生成目标与模块系统

Kotlin/JS 当前实现面向 JavaScript 标准，例如 ES5 和 ES2015。它也能与常见模块系统协作：

  • ESM。
  • CommonJS。
  • UMD。
  • AMD。

模块系统会影响打包、导入导出、与 npm 包协作方式。前端项目中通常还会结合 webpack、Vite 或框架自己的构建链。

npm 依赖

Kotlin/JS 可以从 Gradle 中声明 npm 依赖：

kotlin {
    js {
        browser()
        binaries.executable()
    }

    sourceSets {
        jsMain.dependencies {
            implementation(npm("lodash", "4.17.21"))
        }
    }
}

这让 Kotlin 代码可以集成 JS/TS 生态库，但类型安全取决于是否有 wrapper 或外部声明。

与 JavaScript 互操作

Kotlin/JS 可以调用 JavaScript API。常见方式包括：

  • 使用 Kotlin wrappers。
  • 声明 external 类型。
  • 使用 dynamic。

dynamic 会绕过 Kotlin 类型检查：

val value: dynamic = js("window.location.href")
println(value)

它很灵活，但类型安全下降。公共业务代码中应尽量把 dynamic 限制在边界层，用强类型封装后再进入 Kotlin 领域模型。

external 声明

external fun alert(message: String)

fun showMessage() {
    alert("Hello from Kotlin")
}

external 告诉编译器这个声明由 JavaScript 环境提供，不由 Kotlin 生成实现。它适合为 JS API 建立类型安全入口。

前端开发

Kotlin/JS 可以用于 React 等框架。JetBrains 提供 Kotlin wrappers，帮助 Kotlin 与 React、React Router、Redux、styled-components 等生态集成。

不过前端团队选择 Kotlin/JS 前要认真评估：

  • 团队是否熟悉 Kotlin。
  • 是否需要与 Android/iOS/后端共享逻辑。
  • 与现有 TypeScript 生态的协作成本。
  • IDE、调试、热更新、构建速度是否满足团队预期。

如果只是普通 Web 前端，TypeScript 仍然是生态默认选择。Kotlin/JS 的价值通常来自跨平台共享和 Kotlin 类型系统一致性。

Node.js 与 serverless

Node.js 目标适合：

  • CLI 工具。
  • serverless 函数。
  • 与 JS 生态服务端库集成。
  • 需要快速启动和较低内存占用的场景。

但如果服务端主要依赖 JVM 生态，例如 Spring、Ktor JVM、JPA、Kafka Java client，Kotlin/JVM 通常更自然。

调试与测试

Kotlin/JS 支持运行和调试 JS 项目，也支持测试。实践中要关注：

  • source map 是否正确。
  • 测试运行在 browser 还是 Node.js。
  • 打包产物大小。
  • npm 依赖版本锁定。
  • CI 环境是否安装 Node.js。

Kotlin/JS 与 Kotlin/Wasm

Web 方向现在还包括 Kotlin/Wasm。简单理解：

  • Kotlin/JS 面向 JavaScript 生态，兼容传统 JS 工具链和较老浏览器。
  • Kotlin/Wasm 面向 WebAssembly，适合未来高性能和 Compose Multiplatform Web 等方向。

实际项目可以根据目标浏览器、生态依赖和 UI 技术选择。

实践建议

  • 只有需要 Kotlin 跨平台共享或 Kotlin 前端生态时才引入 Kotlin/JS。
  • JS 互操作尽量用 wrapper 或 external，少让 dynamic 扩散。
  • npm 依赖要锁版本，并在 CI 中验证构建。
  • 公共业务逻辑放 commonMain，浏览器/Node API 放 jsMain。
  • 前端应用要评估 Kotlin/JS 与 TypeScript 团队协作成本。

参考

  • 官方 Kotlin/JS 文档：https://kotlinlang.org/docs/js-overview.html