智控 App 内置 WebView 内核方案排查与落地经验

智控 App 内置 WebView 内核方案排查与落地经验

记录时间：2026-07-29
项目：fndaping / com.fanneng.webview
目标：在 App 层内置固定版本 WebView 内核，降低不同 Android 一体机系统 WebView 版本差异带来的 H5 展示问题。

1. 背景

智控大屏项目主要通过 Android WebView 加载 H5 页面。现场设备系统版本、厂商 ROM 和系统 WebView Provider 差异较大，实际测试中有设备仍停留在 Chromium 83，导致 H5 渲染能力、兼容性和表现不一致。

最初尝试把 webview150.apk 放入：

app/src/main/assets/webview/webview150.apk

期望 App 不依赖系统 WebView，而是固定使用内置版本：

com.google.android.webview / 150.0.7871.48

这里要先明确一个边界：普通 App 不能直接把 Android System WebView APK 当 SDK 一样 new 出一个独立内核。可行路径是使用 WebViewUpgrade 这类 Hook 方案，在 App 进程内、WebView 首次初始化前，把 Framework 查询到的 WebView Provider 信息替换成本地 APK。

2. 方案选型

本次使用开源库：

implementation('io.github.jonanorman.android.webviewup:core:0.1.0') {
    exclude group: 'androidx.appcompat', module: 'appcompat'
}

选择它的原因：

• 不需要 root。
• 不替换系统全局 WebView。
• 只影响当前 App 进程。
• 支持从本地文件、已安装包、assets 等来源准备 WebView Provider。

配套改动：

minSdkVersion 29
compileSdkVersion 33
targetSdkVersion 30

minSdkVersion 提到 29 是因为当前内置 webview150.apk 自身要求 Android 10+。

3. 最终实现方式

3.1 Application 中尽早初始化

必须在任何 android.webkit.WebView 创建之前执行升级逻辑：

@Override
public void onCreate() {
    super.onCreate();
    WebViewKernelManager.upgradeFromAssets(this);
}

3.2 不直接使用 UpgradeAssetSource

一开始直接使用：

new UpgradeAssetSource(context, "webview/webview150.apk", targetFile)

在设备上失败：

java.io.FileNotFoundException: This file can not be opened as a file descriptor; it is probably compressed
at android.content.res.AssetManager.openFd(...)

原因是 UpgradeAssetSource 内部使用 AssetManager.openFd()，它要求 assets 条目必须能以文件描述符方式打开。实际打包后该 APK 可能被压缩，或者在设备环境中无法通过 FD 访问。

最终改为：

1. 使用 assets.open("webview/webview150.apk") 流式读取。
2. 复制到 App 内部目录：/data/user/0/<package>/files/webview/webview150.apk。
3. 使用 UpgradeFileSource 从本地文件升级。

核心思路：

copyAssetToFile(context, "webview/webview150.apk", webViewApk);
WebViewUpgrade.upgrade(new UpgradeFileSource(context, webViewApk));

这样 assets 是否压缩都不再影响读取。

3.3 WebView 打开前等待内核准备完成

内置 APK 约 250MB，首次复制需要时间。项目里 MainActivity 会自动打开 WebViewActivity2，如果不等待，第一次启动可能抢跑到系统 WebView。

处理方式：

• WebViewKernelManager.runWhenReady(...) 接管打开页面动作。
• 内核准备中时先缓存 Runnable。
• 升级成功或失败后再继续打开 WebView 页面。

这样可以避免 WebView 过早初始化。

4. 踩坑记录

4.1 assets APK 被压缩导致 openFd 失败

日志：

FileNotFoundException: This file can not be opened as a file descriptor; it is probably compressed

修复：不用 UpgradeAssetSource，改成 assets.open() 手动复制，再走 UpgradeFileSource。

4.2 Android Studio assemble 出现 Kotlin metadata 报错

现象：Android Studio 执行 assemble 时，release lint 阶段出现 Kotlin metadata 版本不兼容：

Module was compiled with an incompatible version of Kotlin.
The binary version of its metadata is 1.7.1, expected version is 1.5.1.

原因：WebViewUpgrade core:0.1.0 的 POM 传递拉起 androidx.appcompat:appcompat:1.6.1，进而带入 Kotlin 1.7 编译的 AndroidX 依赖；当前工程工具链较老，release lint 会报错。

修复：排除 WebViewUpgrade 的传递 appcompat，继续使用项目原本的 appcompat:1.2.0。

implementation('io.github.jonanorman.android.webviewup:core:0.1.0') {
    exclude group: 'androidx.appcompat', module: 'appcompat'
}

4.3 debug 成功，release 失败

现象：debug APK 能替换到内置 WebView，release APK 仍回落到系统 83。

原因：release 开启了：

minifyEnabled true

WebViewUpgrade 大量依赖反射、注解和动态代理，R8 混淆/优化后会破坏其运行时反射逻辑。

修复：增加 ProGuard 规则：

-keep class com.norman.webviewup.lib.** { *; }
-keep interface com.norman.webviewup.lib.** { *; }
-keep @interface com.norman.webviewup.lib.** { *; }
-keepattributes Signature,*Annotation*,InnerClasses,EnclosingMethod
-dontwarn com.norman.webviewup.lib.**

另外保留 JS Bridge 方法：

-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

5. 原理说明

参考文章：Android 免安装升级系统 WebView 内核探索
https://juejin.cn/post/7340900764364472332#heading-4

Android WebView 初始化时，Framework 会通过系统服务确定当前 WebView Provider。关键链路包括：

• WebViewUpdateService.waitForAndGetProvider
• PackageManagerService.getPackageInfo
• WebViewProviderResponse
• PackageInfo
• WebViewFactoryProvider

WebViewUpgrade 的核心做法是在当前 App 进程内 Hook 两类系统服务调用：

1. Hook WebViewUpdateService，让 waitForAndGetProvider 返回目标 WebView APK 的 Provider 信息。
2. Hook PackageManagerService，让 getPackageInfo 查询目标包时返回本地 APK 解析出的 PackageInfo。

这样，当 App 进程第一次初始化 WebView 时，Framework 以为当前可用的 Provider 是我们指定的本地 APK，从而加载本地 APK 中的 Chromium WebView 实现。

几个关键限制：

• 必须在 WebView 首次初始化前完成替换。
• 不能运行时动态切换已经初始化过的 WebView 内核。
• 本地 APK 的 ABI 必须和设备运行时 ABI 匹配，例如 RK3568 通常是 arm64-v8a。
• PackageInfo 需要包含 native library、签名、meta-data 等信息，否则 WebView 初始化阶段可能崩溃。
• 多进程 WebView 场景复杂，本方案主要按单进程 WebView 使用。

6. 当前项目关键代码点

Gradle 依赖

implementation('io.github.jonanorman.android.webviewup:core:0.1.0') {
    exclude group: 'androidx.appcompat', module: 'appcompat'
}

初始化入口

WebViewKernelManager.upgradeFromAssets(this);

WebView 创建前等待

WebViewKernelManager.runWhenReady(this, new Runnable() {
    @Override
    public void run() {
        startActivity(intent);
    }
});

Release 混淆规则

-keep class com.norman.webviewup.lib.** { *; }
-keep interface com.norman.webviewup.lib.** { *; }
-keep @interface com.norman.webviewup.lib.** { *; }
-keepattributes Signature,*Annotation*,InnerClasses,EnclosingMethod
-dontwarn com.norman.webviewup.lib.**

7. 验证方法

推荐抓日志：

adb logcat -s WebViewKernel MainActivity WebViewActivity2 chromium

重点看：

WebView内核升级完成
升级完成后真实WebView Provider: com.google.android.webview / 150.0.7871.48
WebViewActivity2 findViewById后真实WebView Provider: com.google.android.webview / 150.0.7871.48

如果看到：

com.android.webview / 83.0.4103.120

说明仍然回落到了系统 WebView，需要继续看前面的失败原因。

8. APK 选择建议

当前使用的是：

packageName: com.google.android.webview
versionName: 150.0.7871.48
minSdkVersion: 29
ABI: arm64-v8a

选择 WebView APK 时注意：

• 包名通常选择 com.google.android.webview。
• 设备是 RK3568 / Android 10 时，优先选择 Android 10+ 兼容包。
• ABI 要匹配 arm64-v8a。
• 尽量选择单 APK，不要选择需要 split install 的 .apkm / .xapk。
• 可从 Google Play 或 APKMirror 的 Android System WebView 页面下载对应版本。

9. 结论

这个方案不是把 Chromium SDK 真正嵌入 App，而是在当前 App 进程内 Hook 系统 WebView Provider 查询流程，让系统 WebView 初始化阶段加载我们指定的本地 WebView APK。

最终能跑通的关键点是：

1. WebView APK 放入 assets。
2. App 启动时先复制到内部存储。
3. 用 UpgradeFileSource 替换 Provider。
4. 首个 WebView 创建前等待升级完成。
5. release 下 keep WebViewUpgrade 相关反射代码。
6. 排除 WebViewUpgrade 带来的高版本 appcompat，避免 Kotlin metadata / lint 问题。

本方案适合固定型号、固定系统版本的一体机项目。后续如果设备范围扩大，需要按系统版本、ABI、WebView APK 版本建立兼容矩阵。