webview-footguns

WebView 常见陷阱

从生产环境中的 Kotlin 和 Compose Multiplatform 应用中提炼出的 3 个陷阱，每个都对应 references/ 下的一个简短文件。每个文件都介绍可行模式、陷阱（实际使用中具体如何失败，以及原因），以及包含可在用户自己的代码树上运行的命令的 验证方法 部分。

如何使用此索引。 将即将编写的代码或正在排查的症状与以下条目对应起来：每个条目都注明主题，以及应该让你查看该条目的症状。在提出代码或修复方案之前，使用 Read 工具阅读所有可能适用的文件；每个文件都不到 150 行。如果验证命令中提到了源项目的路径，请替换为用户代码树中的对应路径。

交叉引用。 文件中以反引号标出的陷阱名称若未列在此处，则位于同级技能区域：使用 glob ../*/references/<name>.md 打开它。

低内存手机：启动与渲染进程死亡

• webview-startup-off-the-main-thread — 进程中的第一个 WebView，或几乎任何 android.webkit API 的首次调用，都会在调用线程上承担 WebView 启动开销；就连 Cookie 存储区也会在返回前加载 provider 及其原生库。在内存本就紧张的 3–4 GB 手机上，这会导致 UI 卡住数秒，最终触发 ANR 或进程被杀。介绍如何在后台执行器上启动 WebView 并显示占位内容、库没有防护的执行器、在启动门控前进行的 Cookie 调用，以及之后仍会在主线程上运行的操作。仅适用于 Android。当承载 WebView 的屏幕只在低价手机上打开时冻结数秒、ANR 堆栈最终停在 WebView 构造函数中，或应用在进入网页登录屏幕时退出而开发手机上无法复现时，请查看此条目。
• webview-renderer-gone-takes-the-app — 系统为回收内存而杀死 WebView 的渲染进程时，如果 WebView 的客户端没有处理渲染进程消失回调，整个应用也会随之退出或崩溃——这是从原生代码中发生的，因此不会抛出 Kotlin 异常；只监控 JVM 的崩溃报告工具不会记录，内存不足时甚至什么都不会记录，用户只会看到应用消失。介绍如何让应用创建的每个客户端都返回 true、为何要替换失效实例而不是重新加载、如何构建一个全新的实例以供重试，以及如何故意杀死渲染进程进行测试。仅适用于 Android。当低内存手机上的用户报告应用从网页屏幕消失但崩溃面板中没有记录、系统与其他应用一起强制关闭该应用，或应用从后台返回后网页屏幕一片空白时，请查看此条目。

在 Compose 中承载 WebView

• webview-in-androidview-lifecycle — 在 Compose AndroidView 中承载 WebView 需要具备四项基本工厂未提供的能力：当设备没有可用的 WebView provider、导致构造函数抛出异常时提供回退方案；WebView 离开组合时显式销毁；销毁自身初始化失败的 WebView；以及将副作用绑定到访问过程而非视图，因为视图可能会重建。还介绍 Cookie 存储区会阻塞的 flush，以及尽管存储区中有 Cookie 却返回 null 的 getter。仅适用于 Android。打开网页屏幕时，手表或 WebView provider 加载失败的手机会导致应用崩溃；离开网页屏幕后内存仍然居高不下；重试会让用户退出登录；ANR 堆栈最终停在 Cookie 存储区的 flush 中；或读取 Cookie 时发生空指针错误——调试版本中显示 getCookie(...) must not be null，经过混淆的发布版本中则是在空对象引用上调用 Object.getClass()——请查看此条目。