./gradlew wasmJsBrowserDevelopmentRun,浏览器标签页打开,应用就在那里了。感觉已经完工了。
其实并没有,而原因正是本文的主题。浏览器并不是第四个恰好能渲染同样Compose代码的目标平台。它是一个有着自己规则的主机——什么时机绘制什么内容、谁拥有导航控制权、页面允许获取什么资源、甚至数据库到底是什么。Compose Multiplatform对此毫无遮掩——它只是把你的UI放到画布上,然后你就进入了别人的地盘。
让一个多平台应用能够编译出来,与让它达到生产就绪状态是两回事。下面所有的问题都是在本地能工作,但在用户那里就不行了。
在包到达之前,什么都画不出来
在Android上,用户一点击图标,启动器就会立刻绘制出图标。操作系统拥有那个时刻,你无需任何代价就能获得它。
而在Web上,你什么都得不到。一个空白页面,要等到获取WASM包——大约19MB未压缩,Brotli传输大小约6.5MB——并完成编译之后才会显示。用户不会把这种情况理解为”加载中”,他们会认为页面坏了,然后在第一帧出现之前就离开了。
所以我为Web写的第一样东西,就是Android已经免费给了我十年的东西:一个启动屏。它内联在index.html中,CSS也一起内联,这样它本身不需要额外的请求——一个依赖样式表的启动屏就失去了意义。
颜色值是从core:designsystem中的主题token手动复制过来的,这样画布接手时不会有颜色跳变。这种重复通常我会拒绝接受,但这里别无选择:主题存在于Kotlin代码中,而那个包还没下载下来。
它还有一个已知缺陷,我决定保留。启动屏跟随操作系统的配色方案,而应用本身还尊重用户在设置中手动选择的主题。那些强制设置了与系统不同主题的用户,会在交接瞬间看到一次闪烁。要读取他们的选择,就需要用纯JavaScript解析存储的设置JSON,而把引导页面与那种格式耦合在一起,比一次闪烁更糟糕。
将控制权交还给Kotlin是通过一个全局函数和@JsFun实现的:

@JsFun("() => { if (window.__bikehubHideBootSplash) window.__bikehubHideBootSplash(); }")
private external fun hideBootSplash()

我没做的进度条

显而易见的改进是一个真实的百分比:读取Content-Length,统计到达的字节数,填充进度条。

我研究过但没有做,因为那个数字会撒谎。使用Brotli服务时,Content-Length是压缩后的大小,而流给你的却是解压后的字节,所以计数器会超过100%然后停在那里。修复方法是有的,但没有一个是免费的:通过Gradle任务将真实的未压缩大小写入构建产物,或者把进度条上限设为0.99并希望没人注意到。

在这背后还有一个我没有回答的问题:等待时间到底是下载还是编译?一个由下载字节驱动的进度条到达100%后就停了,而此时浏览器还在编译——一个卡在满格的进度条比没有进度条更糟糕。

最终上线的是一个不会说谎的旋转指示器,加上进度条无论如何也给不了我的东西:一个可见的启动失败状态。30秒后,或者在未捕获错误发生后3秒,旋转指示器会被替换成一条消息和一个重新加载按钮。以前加载失败时,旋转指示器会永远转下去。

这就是这一节最诚实的版本:花哨的功能是错误的问题,而不起眼的失败状态才是正确的问题。

浏览器拥有导航控制权

Compose Multiplatform可以将导航返回栈镜像到浏览器历史记录中:

onNavHostReady = { navController -> navController.bindToBrowserNavigation() }

就这么一行,后退、前进以及地址栏就能驱动应用内导航。这是WASM构建中价值最高的一行代码。

同时它也决定了应用中每一个URL的形状,而这后来变得非常重要。

应用还未加载时的深度链接返回404

BikeHub的导航图在commonMain中声明了深度链接,三个平台共享:

navDeepLink { uriPattern = "$DomainBaseUrl/part-items/{partItemId}" }

Android通过intent filter解析这些链接,iOS通过自己的处理器。Web做不到,原因很有启发性:Web上的深度链接是对Web服务器的请求,而服务器从未听说过你的路由。静态主机只在一个路径上提供应用。向它请求/part-items/42,你会得到404——在任何Kotlin运行之前,甚至在请求包之前就已经发生了。

这在Strava授权流程中变得具体起来:后端需要在用户同意后将用户送回应用。原生路径是bikehub://链接,这在浏览器标签页中根本不起作用。所以后端根据客户端头部分支处理,给Web会话发送302重定向。第一个版本的该重定向指向/strava/auth/success。它返回了404,正如上面所说。

解决方案是将路由放在完全不涉及服务器的地方——URL片段,也就是bindToBrowserNavigation()保存返回栈的地方:

https://app.bike-hub.app/#com.awolity.bikehub.core.navigation.NavigationDestination.StravaBikesSync?authSessionId={id}&outcome={outcome}

浏览器向主机请求/,得到应用,然后应用自行解析剩余部分。不需要主机路由配置,不需要服务器端重写规则,也没有404。

代价就是这个URL。#后面的文本是一个Kotlin类的kotlinx.serialization serialName,这意味着重命名该类或移动其包,会在每个环境中静默地破坏Strava回调,直到后端环境变量更新匹配为止。一个契约测试固定了名称、参数名及其默认值,这样破坏就会在CI中发生,而不是在生产中。


CORS:平台差异触及了后端

这是我最没想到的部分。浏览器的约束改变了后端。

Strava的照片CDN对跨域请求不返回Access-Control-Allow-Origin头部。

Android和iOS不强制执行CORS,所以它们直接加载那些URL,一直没问题。Web构建通过浏览器的fetch()获取图片字节,浏览器丢弃响应,用户只能看到一个占位符。重定向也没用:浏览器跟着重定向走,最终的响应仍然是没有CORS的那个。唯一有效的修复方法是在服务器端读取字节,然后从一个浏览器信任的来源重新提供服务。

所以后端增加了一个图片代理——但只针对需要它的客户端。每个请求都携带X-BikeHubApp-client(android | ios | web),原生客户端继续获取原始URL,这样原生流量完全不走代理。

这里的要点不在于代理本身。而在于浏览器的安全模型是你应用程序架构的一部分。


数据库不是数据库

SQLDelight是最容易迁移的一层(第一部分)——直到Web出现。

在Android和iOS上,生成的schema针对真正的SQLite驱动程序运行。在浏览器中,它在worker中针对sql.js运行,而worker并不执行生成的schema。它从sqljs.schema.sql构建数据库,这是一个手工维护的.sq文件的镜像,必须随着.sq文件的变化手动更新。

这是WASM构建中最危险的东西,而且它不是bug——它是一个没有编译器保护的维护义务。添加一张表,忘记更新镜像,Android和iOS一切正常,而Web以一种没有任何测试能捕捉到的方式坏掉。

将sql.js打包进bundle还需要webpack,这是本次迁移中第一次构建不再仅仅依赖Gradle:

// app/compose/webpack.config.d/sqljs-wasm-copy.js
config.plugins.push(new CopyWebpackPlugin({ patterns: [
  { from: require.resolve("sql.js/dist/sql-wasm.js"),   to: "sql-wasm.js" },
  { from: require.resolve("sql.js/dist/sql-wasm.wasm"), to: "sql-wasm.wasm" },
]}));

一个Kotlin Multiplatform项目里检入了yarn.lock,你会慢慢习惯的。


只在Web上崩溃的小问题

举一个有代表性的长尾案例。WASM媒体选择器返回的是blob:对象URL,Coil的URI解析器在处理部署环境下产生的blob:https://host/id形式时会抛出StringIndexOutOfBoundsException。本地在localhost上一切正常。修复方法是在Coil的内置字符串映射器之前拦截blob URL的映射器,外加一个fetcher,因为Coil默认只通过网络获取http/https——如果没有这个,照片上传时显示的乐观本地缩略图就会渲染成一个占位符。

一个只有在你部署后才会出现的bug,出现在让上传体验变快的代码路径上。这就是Web的一个缩影。


问题找早鸟出海,早鸟出海(NBOVERSEA)深耕出海近十年。专业提供谷歌、苹果APP代上架服务,支持PWA/W2A/H5/APP广告代投,提供Google/Facebook/Tiktok广告账户,谷歌/苹果开发者账户,一站式解决您的后顾之忧。如有任何疑问,请点击服务流程或咨询飞机:@gobird_bot @verygood_appear