>在掌握了 Compose Multiplatform 的基础语法和状态管理之后，我开始思考一个实际的工程问题：同一套代码跑在浏览器（WASM）和桌面（JVM）上时，某些能力的实现方式是截然不同的——比如获取当前时间、生成随机 ID、读取环境变量。前端生态里，我们早就有了一套应对多平台差异的方法论；而 Kotlin Multiplatform 给出的答案，叫做 **expect/actual**。

本文将从前端开发者熟悉的条件编译视角切入，系统讲解 expect/actual 机制的设计思想、三种典型使用场景，以及如何在 WASM 和 Desktop 双平台上落地。

---

## 快速体验 expect/actual 跨平台差异化

### 运行本课程示例

在深入理论之前，先把项目跑起来，直观感受一下同一份 UI 在不同平台上调用不同底层实现的效果：

#### Web 版本（推荐给前端开发者）

```bash
# 克隆项目（如果还没有）
git clone <repository-url>
cd learn-jetpack-compose

# 运行本课程的 WASM 版本
./gradlew :lesson-18-expect-actual:wasmJsBrowserDevelopmentRun
```

运行成功后，浏览器会自动打开 `http://localhost:8080`，你将看到：

- **Demo 1 - 平台标识**：显示 `WASM (Web)`，平台特性说明"运行在浏览器中 / 基于 WebAssembly"
- **Demo 2 - 时间格式化**：由 JavaScript `Date()` 对象输出当前时间，点击"刷新时间"即时更新
- **Demo 3 - UUID 生成**：通过 `Math.random()` 拼接生成符合 v4 格式的 UUID，可批量生成

💡 **前端开发者的优势**：WASM 版本直接跑在浏览器里，不需要任何安装，修改代码后刷新即可看到变化。更关键的是，所有 UI 逻辑和业务逻辑都是 **共用的 Kotlin 代码**，只有底层平台 API 调用才有差异。

#### 桌面版本（可选，需要图形界面环境）

```bash
./gradlew :lesson-18-expect-actual:run
```

桌面版本上，平台标识会变成 `Desktop (JVM)`，时间使用 `java.time.LocalDateTime`，UUID 使用 `java.util.UUID.randomUUID()`。**UI 代码一行不变。**

**效果预览：**

![企业微信截图_32b7db26-84ce-4b52-a4df-5204dbd234d3.png](https://developer.qcloudimg.com/http-save/yehe-320080/fba3e3eef0efb8f452aec4f160879cf1.png)

---

## 从前端视角理解 expect/actual

### 你熟悉的：条件编译与平台分支

在前端开发中，我们处理平台差异有好几种方式：

**方式一：环境变量分支（Vite / Create React App）**

```javascript
// React：通过 process.env 区分环境
function getUUID() {
  if (process.env.PLATFORM === 'web') {
    return crypto.randomUUID();
  } else {
    return require('uuid').v4();
  }
}
```

**方式二：条件导入（Vite 的 glob import）**

```javascript
// Vite：根据平台加载不同实现
const platformModule = import.meta.env.SSR
  ? await import('./platform/server.js')
  : await import('./platform/browser.js');
```

**方式三：开发标志（__DEV__）**

```javascript
// React Native / Webpack：全局开发标志
if (__DEV__) {
  console.log('debug info');
}
```

这些方式都是在**运行时**或**打包时**通过条件判断来切换实现。它们能工作，但有一个共同的痛点：**类型系统无法验证每个平台的实现是否齐全**，遗漏某个平台的实现，往往要等到运行时才会暴露。

### Kotlin 的答案：编译时强制实现

`expect/actual` 是一种**编译时的接口契约**机制：

```kotlin
// commonMain：声明"期望"（接口契约）
expect fun generateUUID(): String

// desktopMain：Desktop 平台的"实际"实现
actual fun generateUUID(): String = UUID.randomUUID().toString()

// wasmJsMain：WASM 平台的"实际"实现
actual fun generateUUID(): String = /* Math.random() 拼接 */
```

**关键差异**：如果你在 `commonMain` 写了 `expect`，但某个平台**忘记写 `actual`**，**编译器直接报错**。这和前端的运行时发现相比，是质的提升。

| 对比维度 | 前端条件编译 | Kotlin expect/actual |
|---------|------------|---------------------|
| 检查时机 | 运行时 / 打包时 | 编译时 |
| 类型安全 | 弱（JS 动态类型） | 强（Kotlin 静态类型） |
| 遗漏检测 | 可能漏掉某个平台 | 编译器强制全覆盖 |
| 代码组织 | 同一文件内分支 / glob import | 不同 sourceSet 目录隔离 |
| 工具支持 | 有限的跨文件跳转 | IDE 可跳转 expect ↔ actual |

---

## 核心概念：expect/actual 机制详解

### sourceSet 架构：先理解目录结构

在 Kotlin Multiplatform 项目中，代码按 **sourceSet** 组织：

```
src/
├── commonMain/        # 共享代码：定义 expect
│   └── kotlin/
│       └── platform/
│           └── Platform.kt        # expect fun getPlatformName()
├── desktopMain/       # Desktop 平台：提供 JVM actual
│   └── kotlin/
│       └── platform/
│           └── Platform.desktop.kt  # actual fun getPlatformName()
└── wasmJsMain/        # WASM 平台：提供 JS actual
    └── kotlin/
        └── platform/
            └── Platform.wasmJs.kt   # actual fun getPlatformName()
```

这和前端的 "platform 目录 + 条件导入" 思路一脉相承，只是 Kotlin 用目录约定代替了运行时判断。

### expect：声明公共契约

`expect` 只能放在 `commonMain`（共享代码目录）。它声明**函数签名、类结构或属性**，不包含实现：

```kotlin
// commonMain/kotlin/org/easonxie/lesson18/platform/Platform.kt
package org.easonxie.lesson18.platform

expect fun getPlatformName(): String
expect fun getCurrentDateTime(): String
expect fun generateUUID(): String
```

**前端类比**：这就像 TypeScript 的接口（`interface`）或抽象类，定义了"这里需要一个实现，但我不关心怎么实现"。

```typescript
// TypeScript 类比
interface PlatformUtils {
  getPlatformName(): string;
  getCurrentDateTime(): string;
  generateUUID(): string;
}
```

### actual：提供平台具体实现

每个目标平台在各自的 sourceSet 里提供 `actual` 实现：

**Desktop 平台（desktopMain）**

```kotlin
// Platform.desktop.kt
package org.easonxie.lesson18.platform

actual fun getPlatformName(): String = "Desktop (JVM)"
```

```kotlin
// DateTimeUtils.desktop.kt
package org.easonxie.lesson18.platform

import java.time.LocalDateTime
import java.time.format.DateTimeFormatter

private val formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")

actual fun getCurrentDateTime(): String {
    return LocalDateTime.now().format(formatter)
}
```

```kotlin
// RandomUtils.desktop.kt
package org.easonxie.lesson18.platform

import java.util.UUID

actual fun generateUUID(): String {
    return UUID.randomUUID().toString()
}
```

**WASM/JS 平台（wasmJsMain）**

WASM 平台需要通过 `external` 声明来访问 JavaScript 的原生 API：

```kotlin
// Platform.wasmJs.kt
package org.easonxie.lesson18.platform

actual fun getPlatformName(): String = "WASM (Web)"
```

```kotlin
// DateTimeUtils.wasmJs.kt
package org.easonxie.lesson18.platform

// 通过 external 声明访问 JS 的 Date 对象
@JsName("Date")
external class JsDate {
    fun getFullYear(): Int
    fun getMonth(): Int       // 0-indexed，注意！
    fun getDate(): Int
    fun getHours(): Int
    fun getMinutes(): Int
    fun getSeconds(): Int
}

actual fun getCurrentDateTime(): String {
    val d = JsDate()
    val year = d.getFullYear()
    val month = (d.getMonth() + 1).toString().padStart(2, '0')
    val day = d.getDate().toString().padStart(2, '0')
    val hour = d.getHours().toString().padStart(2, '0')
    val min = d.getMinutes().toString().padStart(2, '0')
    val sec = d.getSeconds().toString().padStart(2, '0')
    return "$year-$month-$day $hour:$min:$sec"
}
```

```kotlin
// RandomUtils.wasmJs.kt
package org.easonxie.lesson18.platform

@JsName("Math.random")
external fun jsRandom(): Double

// 模拟 UUID v4 格式：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
actual fun generateUUID(): String {
    fun hex(n: Int) = buildString {
        repeat(n) {
            append("0123456789abcdef"[(jsRandom() * 16).toInt()])
        }
    }
    val y = "89ab"[(jsRandom() * 4).toInt()]
    return "${hex(8)}-${hex(4)}-4${hex(3)}-$y${hex(3)}-${hex(12)}"
}
```

💡 **前端开发者注意**：`@JsName("Math.random")` 是 Kotlin/JS 的 JS 互操作机制，类似前端的 `declare function random(): number`（TypeScript 全局声明）。这让你可以在类型安全的 Kotlin 代码里调用任意 JS 全局 API。

---

## 三种典型 expect/actual 场景

### 场景一：平台标识

最简单的场景——返回一个字符串标识当前平台。这在日志、埋点、条件 UI 中很常用：

```kotlin
// commonMain
expect fun getPlatformName(): String

// 使用时（commonMain，不需要知道具体实现）
@Composable
fun PlatformBadge() {
    val platform = remember { getPlatformName() }
    Text("当前平台：$platform")
}
```

**前端等价写法**：
```javascript
// 前端：运行时判断
const platform = typeof window !== 'undefined' ? 'Web' : 'Node.js';
```

**关键差异**：Kotlin 版本在编译时就确定了实现，没有任何运行时开销。

### 场景二：时间格式化

这是 expect/actual 最典型的用例之一——相同的输出格式，不同平台用不同的日期 API：

| 平台 | 使用的 API | 特点 |
|------|-----------|------|
| Desktop (JVM) | `java.time.LocalDateTime` | Java 标准库，精确到纳秒 |
| WASM/JS | `new Date()` | JS 原生日期对象，毫秒级 |

**前端对比**：这就像在 Node.js 服务端用 `dayjs` 格式化时间，在浏览器端也用 `dayjs` 但底层其实调用了不同的 Intl API。表面一致，底层差异。

### 场景三：UUID 生成

UUID 生成场景展示了 expect/actual 处理"有标准库支持"和"需要手动实现"的平台差异：

- **JVM**：`java.util.UUID.randomUUID()` ——标准库直接支持，一行代码
- **WASM/JS**：没有对应的 Kotlin stdlib 支持，需要通过 `@JsName` 调用 `Math.random()` 手写 UUID v4 生成逻辑

这种模式在实际项目中很常见：某些功能在 JVM 生态完善，但在 WASM/JS 端需要手工桥接。

---

## 实战：在 Compose UI 中使用 expect/actual

共享 UI 代码完全不感知底层实现，直接调用 `expect` 函数即可：

```kotlin
// commonMain/kotlin/org/easonxie/lesson18/App.kt
package org.easonxie.lesson18

import androidx.compose.foundation.layout.*
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import org.easonxie.lesson18.demos.DateTimeDemo
import org.easonxie.lesson18.demos.PlatformInfoDemo
import org.easonxie.lesson18.demos.UUIDDemo
import org.easonxie.uicomponents.components.ChineseText

@Composable
fun App() {
    MaterialTheme {
        Surface(modifier = Modifier.fillMaxSize()) {
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .verticalScroll(rememberScrollState())
                    .padding(16.dp),
                verticalArrangement = Arrangement.spacedBy(16.dp)
            ) {
                ChineseText("expect/actual 跨平台差异化")
                PlatformInfoDemo()   // 内部调用 getPlatformName()
                DateTimeDemo()       // 内部调用 getCurrentDateTime()
                UUIDDemo()           // 内部调用 generateUUID()
            }
        }
    }
}
```

### Desktop 入口（desktopMain）

```kotlin
// desktopMain/kotlin/main.kt
package org.easonxie.lesson18

import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

fun main() = application {
    Window(
        onCloseRequest = ::exitApplication,
        title = "Lesson 18: expect/actual 跨平台差异化"
    ) {
        App()
    }
}
```

### WASM 入口（wasmJsMain）

```kotlin
// wasmJsMain/kotlin/main.kt
package org.easonxie.lesson18

import androidx.compose.ui.ExperimentalComposeUiApi
import androidx.compose.ui.window.ComposeViewport
import kotlinx.browser.document

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    ComposeViewport(document.body!!) {
        App()
    }
}
```

两个入口的 `App()` 调用完全相同。差异完全封装在 expect/actual 层。

---

## build.gradle.kts 配置要点

```kotlin
plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
}

kotlin {
    @OptIn(ExperimentalWasmDsl::class)
    wasmJs {
        outputModuleName.set("lesson-18-expect-actual")  // ← 对应 index.html 中的 .js 文件名
        browser {
            commonWebpackConfig {
                outputFileName = "lesson-18-expect-actual.js"
            }
        }
        binaries.executable()
    }

    jvm("desktop")

    sourceSets {
        val desktopMain by getting

        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
            implementation(compose.ui)
            // ⭐ ChineseText 所在的 ui-components 模块
            implementation(project(":ui-components"))
        }
        desktopMain.dependencies {
            implementation(compose.desktop.currentOs)
        }
        // wasmJsMain 无需额外依赖，browser 标准库会自动引入
    }
}
```

**关键配置说明**：

- `outputModuleName.set(...)` 是 Compose Multiplatform 1.8.x 的新写法，旧版用 `outputFileName` 直接赋值
- `wasmJsMain` 的 `actual` 文件默认在 `src/wasmJsMain/kotlin/` 下，无需额外配置 sourceSet 路径
- `desktopMain` 同理，在 `src/desktopMain/kotlin/` 下即自动关联

---

## 我的实践经验

### 踩过的坑：WASM 的 JS 互操作

初次写 WASM 平台的 actual 时，我以为可以像 Kotlin/JS 那样直接用 `js("new Date()")` 内联 JS 代码。但在 WASM 目标下，**不支持 `js()` 内联函数**，必须使用 `external` 声明。

```kotlin
// ❌ 在 wasmJsMain 中无法这样写
actual fun getCurrentDateTime(): String {
    val d = js("new Date()") // 编译错误！
    return d.toString()
}

// ✅ 正确：通过 external class 声明
@JsName("Date")
external class JsDate {
    fun getFullYear(): Int
    // ...
}

actual fun getCurrentDateTime(): String {
    val d = JsDate()
    // ...
}
```

### 踩过的坑：getMonth() 是 0-indexed

JavaScript 的 `Date.getMonth()` 返回 0-11（一月是 0），这和大多数人的直觉不一样。转换时记得 `+1`：

```kotlin
val month = (d.getMonth() + 1).toString().padStart(2, '0')
```

### 最佳实践：expect/actual 的粒度

expect/actual 不一定要用在函数级别，也可以用在**类**、**对象**、**属性**上：

```kotlin
// 类级别的 expect/actual
expect class PlatformContext

// 属性级别
expect val appVersion: String

// 带默认参数的函数（actual 可以扩展参数，但不推荐，易混淆）
expect fun log(message: String)
```

**我的建议**：优先用**函数级别**的 expect/actual，粒度最细，最容易测试和维护。类级别的 expect/actual 会让代码导航复杂一些。

---

## 总结

**核心要点：**

- `expect` 定义跨平台公共契约，`actual` 提供各平台具体实现——这是编译时保证的强类型机制
- 三种典型场景：平台标识（字符串）、时间格式化（标准库差异）、UUID 生成（有无原生支持）
- WASM 平台通过 `external` 声明 + `@JsName` 注解调用 JS 原生 API，不支持 `js()` 内联

**与前端条件编译的核心差异：**

- 前端条件编译（`process.env`、Vite 条件导入）是**打包/运行时**分支，类型系统无法验证完整性
- expect/actual 是**编译时**强制约束，遗漏任何一个平台的实现都会导致编译失败


在掌握了 Compose Multiplatform 的基础语法和状态管理之后，我开始思考一个实际的工程问题：同一套代码跑在浏览器（WASM）和桌面（JVM）上时，某些能力的实现方式是截然不同的——比如获取当前时间、生成随机 ID、读取环境变量。前端生态里，我们早就有了一套应对多平台差异的方法论；而 Kotlin Multiplatform 给出的答案，叫做 expect/actual。

前端开发者的 Kotlin 之旅：expect-actual 跨平台差异化实战

前端开发工程师

前端

编程语言

客户端

Kotlin Multiplatform的expect/actual机制实现跨平台开发，通过编译时强制约束解决平台差异问题。文章详解expect声明公共契约、actual提供具体实现的方法，对比前端条件编译方案，并演示时间格式化、UUID生成等典型场景。包含WASM与JVM平台实战代码，帮助开发者高效实现多平台兼容。

TypeScript

编译器

Kotlin

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

前端开发者的 Kotlin 之旅：expect-actual 跨平台差异化实战-腾讯云开发者社区-腾讯云

前端开发者的 Kotlin 之旅：expect-actual 跨平台差异化实战

前端开发者的 Kotlin 之旅：expect-actual 跨平台差异化实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐