Kotlin Multiplatform 扩展到 Web:先划清边界,再谈代码复用
本文以 Falcon 为背景,讨论将既有多端实时媒体客户端扩展到 Web 时的一般工程判断。文中不涉及具体业务、接口、部署或内部实现细节。
背景:从原生多端到 Web
Falcon 是一个已覆盖 Android、iOS 和 Desktop 的多端实时媒体客户端,涉及视频播放、音视频采集、屏幕共享等能力。
当我们考虑增加 Web 端时,表面上是在为现有产品增加一个运行平台,实际面对的是一次能力边界的重新划分:哪些逻辑可以跨端复用,哪些能力必须遵循浏览器的安全模型、媒体模型与生命周期重新实现。
这并不是一个“把原生页面搬到浏览器”的问题。更准确地说,它是一个产品与工程共同的问题:
- Web 端要承担哪些任务?
- 哪些逻辑的业务语义在所有平台一致?
- 哪些能力天然依赖平台运行环境?
- 当涉及实时媒体时,前端、后端和媒体基础设施分别负责什么?
本文不试图给出一套可以直接复制的架构,而是提供一个适合做前期方案判断的框架。
先定义 Web 的角色,而不是先开始迁移
开始开发前,最值得确认的不是“哪些页面能复用”,而是 Web 在整个产品中的定位。
Web 可以是一个轻量入口,也可以是协作和观看入口,还可以是完整功能端。不同定位会直接影响技术方案、交付范围和跨团队依赖。
如果一开始没有定义边界,项目很容易掉进一个陷阱:将“与原生端功能完全一致”当作默认目标。这个目标听起来合理,但常常既昂贵又不必要。
浏览器有自己的一套规则:
- 用户权限由浏览器和操作系统共同控制;
- 媒体采集和播放受浏览器能力约束;
- 后台标签页的执行与网络行为不等同于原生 App;
- 文件、存储、网络和第三方 SDK 都有不同的运行模型。
因此,更好的问题是:
Web 是否能以符合浏览器特点的方式,稳定地完成它应承担的任务?
这意味着 Web 可以与原生端共享同一个业务目标,却不必拥有相同的技术实现。
按“稳定业务”和“平台能力”划分复用边界
跨端项目中,“能编译”不是共享的充分理由。
更实用的判断方法是:这段代码是否依赖某个平台才成立的假设?如果依赖,那么即使它恰好能被多个 Target 编译,也未必值得共享。
| 更适合共享 | 更适合按平台适配 |
|---|---|
| 数据模型与接口契约 | 会话与本地存储 |
| 表单校验与错误映射 | 文件选择、下载与上传 |
| 领域状态转换 | 媒体采集、播放与设备切换 |
| 主题、设计令牌与尺寸规范 | 浏览器/系统生命周期 |
| 无平台依赖的 UI 结构 | 第三方 SDK 与系统集成 |
这里的重点不是追求最大复用率,而是避免业务规则分叉。
例如,模型字段、校验规则、状态转换这些内容通常有稳定的业务含义;但媒体播放、文件访问、生命周期处理等能力,即使表面上服务于同一个功能,也会因平台能力而有完全不同的实现路径。
一个简单的原则是:
共享业务语义,不共享平台假设。
共享逻辑之前,先找出它依赖的假设
同一个功能名称,并不代表同一种实现可以适用于所有端。
“文件上传”在桌面端可能依赖本地路径;在浏览器中,文件通常以 File 或 Blob 的形式出现,并受到用户手势、权限和内存限制影响。
“保持会话”在原生端可以使用平台提供的安全存储;在浏览器中,则要重新判断刷新、关闭标签页、跨标签页、Token 过期和敏感信息持久化的边界。
“开始播放”在原生端可能只是创建播放器;在浏览器中,还要面对自动播放策略、音频权限、后台节流、编解码支持和跨域资源限制。
所以,在决定共享之前,可以先问三个问题:
- 这段逻辑依赖哪些系统能力?
- 这些能力在浏览器中是否存在等价物?
- 即使有等价物,它们的失败方式和生命周期是否相同?
如果答案不相同,就应该把差异收敛在平台适配层,而不是把分支散落到每一个业务页面中。
实时媒体:播放、采集和屏幕共享不是纯前端问题
实时媒体往往是 Web 扩展中最容易被低估的一部分。
浏览器可以申请摄像头、麦克风和屏幕共享,也可以播放浏览器支持的媒体流。但“拿到画面”“本地预览”和“形成稳定可用的线上实时媒体链路”是三件不同的事。
播放能力:先确认浏览器能消费什么
浏览器并不天然支持所有输入协议和编码组合。拿到一个播放地址,不代表它可以被浏览器连接、解复用、解码和稳定播放。
常见的选择通常是:
- 实时互动、低延迟场景:WebRTC;
- 面向更多观看用户、可接受一定延迟:HLS;
- 需要兼容已有输入流:通过媒体网关完成协议接入、转码或转封装,再输出浏览器可消费的流。
这不是说浏览器“做不了播放”,而是说媒体能力不能只由前端决定。前端负责播放器、交互、状态展示与错误恢复;媒体服务负责接入、转换、分发、鉴权、录制和质量监控。
同时,编解码兼容性、硬件解码能力和网络条件在不同浏览器、设备和操作系统上都可能不同。生产环境应有明确的降级策略:例如切换低码率流、提示更换浏览器、展示错误状态,或回退到静态内容。
摄像头和麦克风:权限只是第一步
浏览器通过 getUserMedia() 提供摄像头和麦克风采集能力,但权限成功并不代表采集链路已经稳定。
实际还要处理:
- 用户拒绝权限或之后撤回权限;
- 没有可用设备,或设备被其他应用占用;
- 多摄像头、多麦克风的设备枚举与切换;
- 外接设备拔出、系统切换输入设备;
- 浏览器切换到后台后的采集、编码或网络变化;
- 用户主动停止采集。
因此,采集能力不应只用一个 isStreaming 布尔值表达,而应建模为有明确终态和错误状态的状态机。下面是与具体框架无关的伪代码:
sealed interface MediaState {
data object Idle : MediaState
data object RequestingPermission : MediaState
data object Previewing : MediaState
data object Connecting : MediaState
data object Publishing : MediaState
data object Stopped : MediaState
data class Failed(
val category: FailureCategory,
val retryable: Boolean
) : MediaState
}
enum class FailureCategory {
PermissionDenied,
DeviceUnavailable,
NetworkInterrupted,
ServerRejected,
BrowserUnsupported
}
这个状态机的价值不在于代码形式,而在于明确区分:用户拒绝、设备不可用、网络异常、服务端拒绝和浏览器不支持,不应被统一处理成“推流失败”。
屏幕共享:浏览器提供采集,但控制权属于用户
屏幕共享通常通过 getDisplayMedia() 实现。它可以完成采集,但浏览器会保留很强的控制权:
- 必须由用户操作触发,不能静默开启;
- 用户自己选择共享屏幕、窗口或标签页;
- 是否能共享系统音频或标签页音频,取决于浏览器和操作系统;
- 用户可以通过浏览器原生控件随时停止共享;
- 共享目标关闭、最小化或切换后,画面可能冻结、降帧或结束。
因此,屏幕共享应被视为“随时可能中断的用户输入”,而不是一个可以被应用长期控制的资源。前端需要监听轨道结束事件,明确展示共享范围、音频状态和停止入口;而媒体服务则需要承接后续的传输、分发、录制和权限控制。
前端、后端与媒体服务如何分工
“Web 端不能直接做某件事”常被误解为“这件事不能实现”。更准确的说法是:它通常无法由前端单独可靠完成。
| 能力 | 浏览器前端主要负责 | 后端与媒体服务主要负责 |
|---|---|---|
| 摄像头/麦克风 | 权限、设备选择、本地预览、交互状态 | 鉴权、信令、媒体转发、录制、质量统计 |
| 屏幕共享 | 用户触发采集、轨道状态、停止处理 | 分发、录制、房间权限、转码 |
| 实时互动 | WebRTC 客户端连接、重连交互、设备切换 | 信令、TURN、SFU、房间管理、带宽策略 |
| 大规模观看 | 播放器、清晰度选择、错误提示 | 流接入、转码、切片、CDN、播放鉴权 |
| 非浏览器原生流 | 展示浏览器可用的输出流 | 协议转换、媒体网关、解码与转封装 |
其中最重要的协作动作是尽早确认:服务端最终能向浏览器提供什么形式的输出?是否存在信令、鉴权、媒体转发或协议转换能力?能否增加媒体网关?
如果这些前置条件尚不存在,前端仍然可以完成设备采集与本地预览,但不能把它等同于“实时媒体功能已上线”。
其他容易被低估的浏览器约束
媒体之外,还有几类问题值得在方案阶段提前确认。
首先是生命周期。页面刷新、标签页隐藏、浏览器后台节流、网络切换都可能改变任务执行状态。恢复到前台时,应重新检查连接和媒体状态,而不是假定一切仍正常。
其次是文件能力。浏览器没有稳定的本地文件路径,应围绕 File、Blob、受控下载和用户选择行为设计。大文件上传还应考虑进度、取消、重试和刷新页面后的恢复策略。
最后是网络与安全环境。HTTPS、CORS、Cookie 或 Token 策略、预检请求、过期后的恢复流程,都应在开发早期联调。只在本地环境请求成功,并不代表浏览器端方案已经成立。
一个务实的推进顺序
如果要将既有客户端扩展到 Web,我会建议按以下顺序推进:
- 定义 Web 的用户任务,以及明确不承担的能力;
- 打通基础会话、路由、错误处理和网络环境;
- 优先迁移模型、校验、状态转换等稳定业务逻辑;
- 将文件、生命周期和第三方 SDK 放在平台适配层;
- 与后端、媒体服务共同跑通最小端到端媒体链路;
- 最后补齐弱网、设备切换、后台恢复、监控和降级策略。
验证也应分层:编译通过、自动化测试、服务联调、真实浏览器与设备验证,分别代表不同程度的完成,不能互相替代。
结语
将既有客户端扩展到 Web,不是多编译一个 Target,而是在浏览器的安全模型、媒体模型和生命周期约束下,重新设计一部分能力。
Kotlin Multiplatform 的价值不在于让所有平台共享同一份实现,而在于帮助团队更清楚地区分:哪些是稳定的业务本质,哪些只是特定平台上的实现方式。
好的跨端架构,不是让每个平台看起来完全相同;而是让每个平台都能以适合自己的方式,稳定地承载同一个业务目标。