Android WebView 内核动态升级方案：WebViewUpgrade 库实战

模块化结构允许开发者仅包含所需组件——仅需核心模块进行基于资源的升级，或同时包含核心和下载源模块以实现远程 APK 功能。

可视化演示

升级过程将 WebView 环境从受限的系统实现转换为功能齐全的现代内核：

升级前：在华为设备上，WebView 内核运行版本为 14.0.0.331 的 com.huawei.webview，Chromium 版本为 99.0.4844.88，不支持 H265。

升级后：内核切换到 Chromium 版本为 122.0.6261.64 的 com.google.android.webview，启用完整的 H265 视频播放功能。

快速开始

WebViewUpgrade 的作用

WebViewUpgrade 解决了 Android 开发中的一个关键问题：无需用户从 Google Play 安装 APK 即可升级 WebView 内核。这对于华为和亚马逊等制造商的设备尤其有价值，这些设备的系统 WebView 中的 Chromium 版本通常过时，无法支持 H265 视频播放等现代 Web 标准（需要 Chromium 107+）。

升级过程会动态加载更新的 WebView 内核并替换系统 WebView 的功能，同时你的应用继续运行。

前置条件

在集成 WebViewUpgrade 之前，请确保你的项目满足以下要求：

基本功能不需要在 AndroidManifest.xml 中添加特殊权限。

添加依赖项

将 WebViewUpgrade 依赖项添加到你的应用模块的 build.gradle 文件中。根据你的升级策略选择合适的组合：

dependencies {
    // 核心库 - 始终必需
    implementation 'io.github.jonanorman.android.webviewup:core:0.1.0'
    // 下载源模块 - 远程 APK 下载必需
    implementation 'io.github.jonanorman.android.webviewup:download-source:0.1.0'
}

如果你不从网络下载 APK（例如仅使用内置资源或已安装的包），可以省略 download-source 依赖项。

基本实现

根据你的用例选择三种升级策略之一：

策略 1：远程 APK 下载

在运行时从远程 URL 下载 WebView APK。这是最灵活的方法，但需要网络连接。

import com.norman.webviewup.lib.WebViewUpgrade;
import com.norman.webviewup.lib.source.download.UpgradeDownloadSource;
import java.io.File;

// 定义下载源
UpgradeDownloadSource upgradeSource = new UpgradeDownloadSource(
    context,
    "https://example.com/webview-arm64-v8a.apk",
    new File(context.getFilesDir(), "webview/upgraded.apk")
);

// 触发升级
WebViewUpgrade.upgrade(upgradeSource);

策略 2：内置资源 APK

将 WebView APK 打包到你的应用中以进行离线升级。这确保了可靠性，但会增加应用大小。

import com.norman.webviewup.lib.source.UpgradeAssetSource;

// 使用 assets 文件夹中的 APK
UpgradeAssetSource upgradeSource = new UpgradeAssetSource(
    context,
    "webview_apk_path.apk",
    new File(context.getFilesDir(), "webview/upgraded.apk")
);

// 触发升级
WebViewUpgrade.upgrade(upgradeSource);

将你的 WebView APK 文件放在 app/src/main/assets/ 目录中，并通过文件名引用。

策略 3：已安装包源

使用已安装的 WebView 包（如 Chrome）作为升级源。

import com.norman.webviewup.lib.source.UpgradePackageSource;

// 使用已安装的 Chrome
UpgradePackageSource upgradeSource = new UpgradePackageSource(
    context,
    "com.android.chrome"
);

// 触发升级
WebViewUpgrade.upgrade(upgradeSource);

监控升级进度

实现 UpgradeCallback 接口以在升级过程中接收实时更新：

import com.norman.webviewup.lib.UpgradeCallback;
import com.norman.webviewup.lib.WebViewUpgrade;

public class MyActivity extends Activity implements UpgradeCallback {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // 注册回调
        WebViewUpgrade.addUpgradeCallback(this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        // 取消注册回调
        WebViewUpgrade.removeUpgradeCallback(this);
    }

    @Override
    public void onUpgradeProcess(float percent) {
        // 更新进度条（percent 范围从 0.0 到 1.0）
        int progress = (int) (percent * 100);
        progressBar.setProgress(progress);
    }

    @Override
    public void onUpgradeComplete() {
        // 升级成功 - WebView 现在使用新内核
        Toast.makeText(this, "WebView 升级成功", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onUpgradeError(Throwable throwable) {
        // 升级失败 - 适当处理错误
        Log.e("Upgrade", "错误：" + throwable.getMessage(), throwable);
        Toast.makeText(this, "升级失败：" + throwable.getMessage(), Toast.LENGTH_SHORT).show();
    }
}

你也可以使用这些静态方法同步检查升级状态：

完整示例

这是一个结合所有元素的完整工作示例：

import android.app.Activity;
import android.os.Bundle;
import android.widget.ProgressBar;
import android.widget.Toast;
import com.norman.webviewup.lib.WebViewUpgrade;
import com.norman.webviewup.lib.source.download.UpgradeDownloadSource;
import com.norman.webviewup.lib.UpgradeCallback;
import java.io.File;

public class MainActivity extends Activity implements UpgradeCallback {
    private ProgressBar progressBar;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        progressBar = findViewById(R.id.progressBar);
        WebViewUpgrade.addUpgradeCallback(this);
        // 使用 Google WebView 触发升级
        performUpgrade();
    }

    private void performUpgrade() {
        String architecture = getCurrentArchitecture(); // arm, arm64, x86, 或 x86_64
        String url = getWebViewUrlForArchitecture(architecture);
        UpgradeDownloadSource source = new UpgradeDownloadSource(
            this,
            url,
            new File(getFilesDir(), "webview/" + architecture + ".apk")
        );
        WebViewUpgrade.upgrade(source);
    }

    @Override
    public void onUpgradeProcess(float percent) {
        progressBar.setProgress((int) (percent * 100));
    }

    @Override
    public void onUpgradeComplete() {
        Toast.makeText(this, "升级完成！", Toast.LENGTH_SHORT).show();
        // 现在你可以创建使用升级后内核的 WebView
    }

    @Override
    public void onUpgradeError(Throwable throwable) {
        Toast.makeText(this, "升级失败：" + throwable.getMessage(), Toast.LENGTH_LONG).show();
    }

    @Override
    protected void onDestroy() {
        WebViewUpgrade.removeUpgradeCallback(this);
        super.onDestroy();
    }
}

依赖设置与 Gradle 配置

项目结构概述

WebViewUpgrade 采用模块化架构，包含三个主要组件：

Gradle 配置先决条件

根项目设置

使用 Android Gradle 插件和必要的仓库声明配置你的根 build.gradle：

buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.3.1'
    }
}

allprojects {
    repositories {
        mavenCentral()
        google()
        maven { url 'https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/' }
        maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }
    }
}

模块配置摘要

确保你项目的 compileSdk 至少为 35 以匹配库配置，虽然 minSdkVersion 为 21 可保持广泛的设备兼容性。该库使用 Java 8 兼容性，与 Android Gradle Plugin 8.x 和更新的工具链兼容。

依赖配置方法

方法 1：远程依赖（推荐）

将这些依赖项添加到你的应用模块的 build.gradle 中：

dependencies {
    // 核心功能 - 始终必需
    implementation 'io.github.jonanorman.android.webviewup:core:0.1.0'
    // 可选：如果你需要远程 APK 下载，请添加下载源
    implementation 'io.github.jonanorman.android.webviewup:download-source:0.1.0'
}

方法 2：本地模块集成

如果你偏好本地开发或自定义，请直接包含模块：

dependencies {
    implementation project(":core")
    implementation project(':download-source') // 可选
}

附加依赖

download-source 模块包含用于下载管理的 Aria：

// 已包含在 download-source 模块中
implementation 'me.laoyuyu.aria:core:3.8.16'

Aria 库提供强大的文件下载功能，支持暂停/恢复，这对于处理大型 WebView APK 下载（通常 50-100MB）在不同网络条件下至关重要。

构建配置选项

应用模块设置

使用基本设置配置你的应用模块的 build.gradle：

android {
    defaultConfig {
        compileSdk 35
        minSdkVersion 21
        targetSdkVersion 35
    }
    // 重要：不要压缩 APK 文件
    aaptOptions {
        noCompress "apk"
    }
    // WebView 的 JNI 库
    sourceSets {
        main {
            jniLibs.srcDirs = ["libs"]
        }
    }
}

基础 WebView 升级实现

实现概述

升级过程遵循三步架构模式：来源创建、升级执行和进度监控。这种设计将升级来源与核心升级逻辑分离，使获取和加载 WebView APK 包的方式更加灵活。

升级来源类型

该库提供了三种获取 WebView 升级包的实现策略，每种策略适用于不同的部署场景：

执行升级

配置好 UpgradeSource 后，通过 WebViewUpgrade 单例启动升级过程：

WebViewUpgrade.upgrade(upgradeSource);

执行前，检查当前升级状态以防止重复操作：

if (WebViewUpgrade.isProcessing()) {
    Toast.makeText(getApplicationContext(), "webView 正在升级中，请稍候", Toast.LENGTH_LONG).show();
} else if (WebViewUpgrade.isCompleted()) {
    Toast.makeText(getApplicationContext(), "webView 已升级成功，不支持动态切换", Toast.LENGTH_LONG).show();
} else {
    WebViewUpgrade.upgrade(upgradeSource);
}

查询升级状态

该库提供静态方法以在任何时间点检查当前升级状态：

系统 WebView 信息查询

升级前，查询当前系统 WebView 详细信息以做出明智的升级决策：

private void updateSystemWebViewPackageInfo() {
    String systemWebViewPackageName = WebViewUpgrade.getSystemWebViewPackageName();
    String systemWebViewPackageVersion = WebViewUpgrade.getSystemWebViewPackageVersion();
    String systemWebViewPackageInfo = "unknown";
    if (!TextUtils.isEmpty(systemWebViewPackageName) || !TextUtils.isEmpty(systemWebViewPackageVersion)) {
        systemWebViewPackageInfo = (!TextUtils.isEmpty(systemWebViewPackageName) ? systemWebViewPackageName : "unknown") + ":" + (!TextUtils.isEmpty(systemWebViewPackageVersion) ? systemWebViewPackageVersion : "unknown");
    }
    systemWebViewPackageTextView.setText(systemWebViewPackageInfo);
}

模块概述

项目架构概览

WebViewUpgrade 项目组织为三个独立的模块，协同工作以提供完整的 WebView 升级解决方案。这种模块化设计允许开发者选择所需的确切组件，保持应用的轻量高效。

该架构展示了层次化的依赖关系：演示应用依赖于核心模块和下载源模块，而下载源模块本身又依赖于核心模块。这种设计模式确保核心功能完全独立，在不需要 APK 下载能力时可以独立使用。

核心模块 (core/)

核心模块是 WebViewUpgrade 库的基础，包含基本的升级逻辑和接口。该模块设计为 Android 库，可集成到任何需要 WebView 升级功能的项目中。

模块特性

核心模块完全自包含，不需要网络权限，适用于 WebView APK 文件作为资源打包或从已安装包获取的场景。最小的依赖足迹确保不会显著影响应用大小。

关键组件

核心模块提供升级过程的基本类和接口：

• WebViewUpgrade：协调升级过程的主类，管理来源选择、APK 加载和 WebView 内核替换
• UpgradeCallback：用于监控升级进度和接收完成/错误回调的接口
• UpgradeSource：定义如何获取 WebView APK 文件的基础接口
• UpgradeAssetSource：从应用资源加载 WebView 的实现
• UpgradePackageSource：使用已安装 WebView 包的实现
• VersionUtils：用于版本比较和 UserAgent 解析的工具类
• ProcessUtils：用于检测设备 CPU 架构（arm、arm64、x86、x86_64）的工具类

下载源模块 (download-source/)

下载源模块通过提供远程 APK 下载功能扩展了核心库。这是一个可选模块，仅在你想从互联网动态下载 WebView 包时才需要。

模块特性

下载源模块使用 Aria 下载库，这是一个强大高效的 Android 下载框架，支持暂停、恢复和多线程下载。

关键功能

下载源模块提供：

• UpgradeDownloadSource：UpgradeSource 的实现，从远程 URL 下载 WebView APK 文件
• 自动文件管理：处理下载存储、缓存管理和文件清理
• 进度跟踪：与核心模块的 UpgradeCallback 系统集成
• 网络状态感知：响应网络变化和连接问题
• 后台下载支持：可以处理大型 APK 文件而不阻塞主线程

演示应用模块 (app/)

演示应用既是参考实现，也是 WebViewUpgrade 库的测试平台。它展示了所有可用的升级来源，并提供了如何将库集成到实际应用中的实际示例。

模块特性

应用结构

演示应用由三个主要组件组成：

1. MainActivity：主活动提供用于选择和启动 WebView 升级的用户界面
2. WebViewActivity：一个测试页面，展示升级后的 WebView 的实际运行情况
3. MyApp：处理升级系统初始化和生命周期管理的应用类

架构与设计理念

架构概述

WebViewUpgrade 采用模块化单体架构，通过库模块明确定义功能边界，使开发者能够仅包含必要的功能。系统由三个不同的模块组成：核心库、下载源扩展和演示应用，每个模块在升级生态系统中承担特定职责。

该架构以 WebViewUpgrade 外观模式为中心，将内核替换的复杂性抽象在简单的静态 API 表面之后。这种设计使开发者能够用最少的代码升级 WebView 内核，而库则在幕后处理 APK 加载、资源提取和系统集成等复杂细节。

模块架构

核心库模块

核心模块（com.norman.webviewup.lib）是架构的基础，包含 WebView 内核升级功能所需的所有基本类和接口。该模块提供了 UpgradeSource 抽象，定义了从各种来源获取 WebView APK 文件的契约，以及用于监控升级进度和状态变化的 UpgradeCallback 接口。

核心模块设计为自包含且依赖最小化，仅需要 androidx.appcompat 来实现基本的 Android 功能。这种轻量级依赖足迹确保应用程序可以在不引入不必要的膨胀或冲突风险的情况下集成该库。

下载源扩展模块

下载源模块（com.norman.webviewup.lib.source.download）通过提供基于网络的 APK 下载功能扩展了核心库。该模块使用 Aria 下载库实现远程文件检索，使应用程序能够通过从远程服务器下载包来升级 WebView 内核。

该模块展示了架构的可扩展性理念——它是可选的，当不需要基于网络的升级时可以排除。该模块在编译时仅依赖于核心模块（compileOnly），展示了库对依赖倒置的承诺，其中抽象而非具体实现驱动设计。

演示应用模块

应用模块既是功能演示也是集成参考，展示了如何在真实的 Android 应用程序中实现 WebView 升级。演示提供了所有三种升级源实现（网络下载、捆绑资源和已安装包）的实际示例，并包括用于选择和启动升级的用户界面。

值得注意的是，应用模块在特定架构的目录（libs/arm64-v8a、libs/armeabi-v7a）中包含 WebView APK 文件，展示了开发者如何将升级包直接捆绑在他们的应用程序中以支持离线升级。

设计理念

源抽象策略

架构通过 UpgradeSource 接口采用策略模式，支持多种 APK 获取方法，同时保持统一的升级 API。这种抽象支持三种具体实现，每种实现解决不同的用例：

• UpgradeDownloadSource：从网络 URL 检索 APK 文件，实现远程内核更新
• UpgradeAssetSource：从应用程序资源加载 APK 文件，支持离线升级
• UpgradePackageSource：使用已安装的应用程序包，实现系统级集成

这种设计允许开发者为他们的应用程序上下文选择最合适的升级源，而无需修改核心升级逻辑。基于接口的方法还便于为特殊需求实现自定义实现。

基于回调的进度监控

UpgradeCallback 接口为监控升级操作提供了发布者 - 订阅者模式。回调通过注册方法（addUpgradeCallback、removeUpgradeCallback）支持多个并发监听器，使应用程序的不同组件能够独立响应升级事件。

回调系统提供三个基本通知：

• 进度更新（onUpgradeProcess）用于 UI 反馈
• 完成通知（onUpgradeComplete）用于升级后操作
• 错误报告（onUpgradeError）用于故障处理

这种设计将升级执行与进度展示分离，允许应用程序实现自定义 UI 体验，而无需耦合到特定的实现细节。

架构特定包支持

系统认识到 Android 生态系统中的碎片化挑战，并提供架构感知的包选择。演示应用程序通过按 CPU 架构（arm、arm64、x86、x86_64）键入的包映射来展示这一点，每个映射包含兼容的 WebView 包的精选列表。

这种设计理念承认 WebView 内核必须与设备的 CPU 指令集匹配才能正常运行。通过按架构组织包，系统确保兼容性，同时支持多样化的 Android 设备生态系统。

多厂商兼容性策略

WebViewUpgrade 通过支持多种 WebView 实现的厂商无关架构解决了 OEM WebView 碎片化问题。该系统已在主要 WebView 包中进行了验证，包括 Google Android WebView、System WebView、华为 WebView、Chrome 和 Amazon WebView Chromium。

文档中的兼容性表展示了不同厂商的测试版本，Chrome 版本达到 122.0.6261.43，Google WebView 为 122.0.6261.64。这种跨厂商支持使应用程序能够摆脱设备特定 WebView 实现的限制，这对于需要 Chromium 107 或更高版本的 H265 视频播放等场景尤为重要。

核心功能实现

WebViewUpgrade 类与升级流程

WebViewUpgrade 类是所有 WebView 内核升级操作的主要入口点。它作为一个门面，协调升级来源、进程管理和进度监控系统。该类位于 com.norman.webviewup.lib 包中，采用受单例模式启发的设计来管理应用程序整个生命周期内的升级状态。

核心设计原则

该类围绕三个基本架构原则设计：状态管理、来源抽象和进度通知。它维护一个集中式状态，跟踪升级操作是否正在进行中，防止可能导致资源冲突或状态不一致的并发升级尝试。来源抽象层允许升级机制通过统一接口与不同的 APK 来源——远程下载、嵌入式资源或已安装包——协同工作。进度通知系统通过回调注册和注销方法，实现对应用程序层的实时反馈。

核心方法

// 启动升级过程
public static void upgrade(UpgradeSource source)

// 状态查询方法
public static boolean isProcessing()
public static boolean isCompleted()
public static boolean isFailed()
public static float getUpgradeProcess()
public static Throwable getUpgradeError()

// 回调管理
public static void addUpgradeCallback(UpgradeCallback callback)
public static void removeUpgradeCallback(UpgradeCallback callback)

// 系统信息查询
public static String getSystemWebViewPackageName()
public static String getSystemWebViewPackageVersion()

升级流程的六个阶段

升级过程可分为六个不同的阶段，每个阶段都有特定的职责和潜在的故障点：

1. 状态验证和初始化：检查确保当前没有升级操作正在进行
2. 来源选择和 APK 获取：根据应用程序配置选择适当的 UpgradeSource 实现
3. 验证和完整性检查：获取的 APK 在升级继续之前会经过全面验证
4. Native 库提取和配置：从 APK 中解压适当的共享库并准备加载
5. ClassLoader 配置和内核替换：提取的库被配置到自定义类加载器中
6. 完成通知和状态清理：触发成功回调、更新内部状态以反映完成

UpgradeSource 接口与实现策略

UpgradeSource 接口作为 WebView 内核升级操作的基础抽象，通过多种实现策略实现灵活的来源配置。这种策略性设计模式允许应用程序从各种来源（网络下载、捆绑资源或已安装包）获取 WebView APK，同时保持统一的升级接口。

接口架构与设计模式

UpgradeSource 接口遵循策略模式，将获取 WebView 升级包的不同方法封装在一致的抽象层后。这种架构方法将升级过程与来源获取关注点解耦，使运行时能够根据部署要求、设备功能和网络条件选择最合适的来源策略。

核心库提供了三种具体实现，每种实现解决不同的升级来源场景：

• UpgradeDownloadSource：从远程网络位置获取 WebView APK
• UpgradeAssetSource：从应用程序资源包加载 WebView APK
• UpgradePackageSource：利用设备上已安装的 WebView 包

实现选择矩阵

选择合适的 UpgradeSource 实现需要仔细考虑部署约束、设备功能和应用程序要求：

UpgradeCallback 系统

UpgradeCallback 系统提供了一套全面的事件驱动架构，用于监控和响应 WebView 升级过程的生命周期。该回调接口使应用程序能够实时跟踪升级进度、处理完成事件，并通过简洁的抽象层管理错误场景。

回调接口架构

UpgradeCallback 接口定义了三个核心方法，分别对应升级生命周期的三个主要状态：进行中、已完成和失败。这种三状态模型确保所有可能的升级结果都能得到明确处理，防止静默失败或模糊状态。

public interface UpgradeCallback {
    void onUpgradeProcess(float percent); // 0.0 到 1.0 之间的进度值
    void onUpgradeComplete(); // 升级成功完成
    void onUpgradeError(Throwable throwable); // 升级失败，提供错误详情
}

回调注册与生命周期管理

WebViewUpgrade 类通过 addUpgradeCallback(UpgradeCallback) 和 removeUpgradeCallback(UpgradeCallback) 方法维护 UpgradeCallback 实例的注册表。这种观察者模式实现支持多个同时回调，使应用程序的不同组件能够独立响应升级事件。

重要：始终在 onDestroy() 或等效生命周期方法中移除回调以防止内存泄漏，特别是对于可能因配置更改而被销毁和重建的长生命周期组件（如 Activity 和 Fragment）。

状态查询方法与进度跟踪

除回调接口外，WebViewUpgrade 还提供了同步方法用于查询升级状态和检索详细进度信息：

升级源类型

UpgradeDownloadSource：远程 APK 下载

UpgradeDownloadSource 提供了从远程服务器下载 WebView 升级包的功能，支持动态版本更新，而无需在应用程序中捆绑 APK。该实现利用 Aria 下载库进行高效的网络操作，并自动处理文件管理，非常适合需要灵活的 WebView 版本管理或减小应用程序大小的场景。

基本设置

要使用 UpgradeDownloadSource，必须在应用程序的 Gradle 配置中包含 download-source 模块依赖项：

implementation 'io.github.jonanorman.android.webviewup:core:0.1.0'
implementation 'io.github.jonanorman.android.webviewup:download-source:0.1.0'

构造函数参数

UpgradeDownloadSource 需要三个基本参数来初始化下载和升级过程：

实例化示例

UpgradeDownloadSource upgradeSource = new UpgradeDownloadSource(
    context,
    "https://example.com/path/to/webview.apk",
    new File(context.getFilesDir(), "com.google.android.webview/122.0.6261.64.apk")
);
WebViewUpgrade.upgrade(upgradeSource);

在应用程序的私有目录中按包名和版本组织下载的文件，以避免冲突并便于清理。packageName/versionName.apk 模式确保每个 WebView 变体都有唯一的存储位置。

配置与最佳实践

文件位置策略：

URL 管理：

• 架构特定 URL：为 arm64-v8a、armeabi-v7a、x86 和 x86_64 架构提供单独的 URL
• 版本跟踪：在 URL 路径和文件命名约定中包含版本信息
• 冗余：考虑镜像 URL 以提高可靠性

UpgradeAssetSource：内置 APK 资源

UpgradeAssetSource 提供了一种使用直接打包在应用 assets 目录中的 APK 文件来升级 WebView 内核的机制。这种方法消除了升级过程中的网络依赖，实现了离线功能和确定性的升级行为，同时确保 WebView 组件的即时可用性。

实现配置

要有效实现 UpgradeAssetSource，必须正确配置项目以将 APK 文件作为资源处理。构建系统需要特定的指令来防止 APK 压缩，这会干扰升级过程。

Gradle 配置：

aaptOptions {
    noCompress "apk"
}

资源结构：将 WebView 升级 APK 放置在 app/src/main/assets/ 目录中。UpgradeAssetSource 构造中指定的文件路径必须与此目录的相对路径匹配。

源实例化模式

UpgradeSource upgradeSource = new UpgradeAssetSource(
    getApplicationContext(),
    "com.webview.chromium_118-5993-tv.5993.155.51_armeabi-v7a.apk",
    new File(getApplicationContext().getFilesDir(), "com.amazon.webview.chromium/118-5993-tv.5993.155.51.apk")
);

构造函数接受三个参数：

• Context：用于访问 AssetManager 和文件操作的应用上下文
• Asset Path：assets 目录中 APK 文件的相对路径
• Destination File：内部存储中 APK 将被复制的目标位置

升级源比较

优势和限制

主要优势：

• 网络独立性：消除了升级操作期间对外部服务器或网络连接的依赖
• 可预测性能：资源提取在本地进行，具有确定性的时间特性
• 版本控制：APK 版本锁定到应用程序发布，防止意外版本更改
• 安全性：无外部下载向量减少了升级过程中的攻击面
• 可靠性：消除了网络相关的故障模式，如超时、速率限制或 DNS 解析问题

操作限制：

• 应用大小：每个嵌入的 APK 都会增加基础应用大小，可能影响下载时间和存储要求
• 更新延迟：新的 WebView 版本需要应用更新，而不是实时部署
• 存储重复：APK 同时存在于应用资源和提取形式中，在升级期间临时消耗额外存储
• 平台特定性：嵌入的 APK 是架构特定的，可能需要多个应用变体以支持通用设备

UpgradePackageSource：使用已安装包

UpgradePackageSource 提供了一种便捷的方式来升级 WebView 内核，它利用用户设备上已安装的软件包来实现这一目的。这种方法无需下载或捆绑 APK 文件，非常适合使用用户已安装的 Chrome 或其他兼容 WebView 的浏览器的场景。

概述与用例

UpgradePackageSource 是 UpgradeSource 接口的三个实现策略之一，与 UpgradeDownloadSource（用于远程下载）和 UpgradeAssetSource（用于内置资源）并列。当你的目标用户设备上已安装兼容的 WebView 软件包（如 Chrome 浏览器或制造商特定的 WebView 实现）时，软件包源策略特别有价值。

常见用例：

• 利用已安装的 Chrome 浏览器作为 WebView 内核，无需单独下载
• 切换到制造商 WebView 软件包，这些软件包在特定设备上可能具有更好的性能
• 在网络下载不可行时提供后备选项
• 通过避免嵌入 APK 资源来减小应用程序包大小

基本用法

构造函数参数：

实现示例：

// 为 Chrome 创建 UpgradePackageSource
UpgradeSource upgradeSource = new UpgradePackageSource(getApplicationContext(), "com.android.chrome");
// 启动升级过程
WebViewUpgrade.upgrade(upgradeSource);

支持的软件包名称

在尝试使用 UpgradePackageSource 之前，务必验证目标软件包确实已安装在设备上。你可以使用 PackageManager.getPackageInfo() 来检查软件包可用性。

错误处理与验证

使用 UpgradePackageSource 时，你应该实施适当的验证以确保流畅的升级体验：

private boolean isPackageAvailable(String packageName) {
    try {
        PackageManager pm = getApplicationContext().getPackageManager();
        PackageInfo packageInfo = pm.getPackageInfo(packageName, 0);
        return packageInfo != null;
    } catch (PackageManager.NameNotFoundException e) {
        return false;
    }
}

// 带验证的增强用法
String packageName = "com.android.chrome";
if (isPackageAvailable(packageName)) {
    UpgradeSource source = new UpgradePackageSource(getApplicationContext(), packageName);
    WebViewUpgrade.upgrade(source);
} else {
    // 处理软件包未安装的情况
    // 回退到下载或资源源
    Toast.makeText(this, "所需软件包未安装", Toast.LENGTH_SHORT).show();
}

考虑实施回退策略，首先尝试 UpgradePackageSource，如果目标软件包在设备上不可用，则回退到 UpgradeDownloadSource 或 UpgradeAssetSource。

支持的 WebView 包与版本

WebView 包类型

该库支持不同制造商和分发渠道的多种 WebView 包类型。每种包类型都有独特的特性和兼容性要求：

每种包类型对应特定的 Chromium 引擎实现，并拥有自己的版本编号方案。上述显示的版本号代表每个包内嵌的 Chromium 核心版本，它们决定了支持的 Web 标准和功能。值得注意的是，不同制造商可能使用不同的版本格式（例如，华为的 14.0.0.331 与 Google 的 122.0.6261.64）。

架构特定版本矩阵

WebView 包必须与设备的 CPU 架构（指令集）匹配。该库会自动检测当前架构并提供相应的升级包：

架构检测通过 ProcessUtils.getCurrentInstruction() 方法执行，该方法查询 VM 运行时以获取当前指令集，或回退到分析设备支持的 ABI。

设备制造商兼容性

不同的 Android 制造商为其设备配备不同的默认 WebView 包。了解这些预安装配置有助于确定哪些升级目标能提供有意义的改进：

版本检测和比较系统

该库提供了检测系统和升级 WebView 包版本的工具，并具备复杂的版本比较功能：

// 获取当前系统 WebView 信息
String systemPackage = WebViewUpgrade.getSystemWebViewPackageName();
String systemVersion = WebViewUpgrade.getSystemWebViewPackageVersion();

// 获取升级后的 WebView 信息
String upgradePackage = WebViewUpgrade.getUpgradeWebViewPackageName();
String upgradeVersion = WebViewUpgrade.getUpgradeWebViewVersion();

// 以编程方式比较版本
int comparison = VersionUtils.compareVersion(systemVersion, upgradeVersion);
// 返回值：<0 表示 version1 < version2，=0 表示相等，>0 表示 version1 > version2

VersionUtils.compareVersion() 方法实现了语义版本比较，可处理不同制造商的各种版本格式。此比较逻辑可正确处理如下版本字符串：

• "122.0.6261.64" vs "113.0.5672.136" → 正确识别 122 更新
• "14.0.0.331" vs "99.0.4844.88" → 正确识别 99 更新
• "118-5993-tv.5993.155.51" → 带连字符的替代格式

重要：为功能支持（如 H265）升级 WebView 时，务必比较 UserAgent 中的实际 Chromium 版本，而非包版本。在制造商特定的 WebView 上，包版本（例如华为的 14.0.0.331）和 Chromium 版本（例如 99.0.4844.88）可能存在显著差异。

Chromium 版本功能兼容性

升级 WebView 版本的主要动机是功能兼容性。不同的 Chromium 版本支持特定的 Web 功能：

架构特定升级包

架构检测机制

多架构支持的基础在于自动检测设备当前的指令集架构。该库使用 ProcessUtils.getCurrentInstruction() 来确定适合当前运行时环境的 WebView 包。

架构检测遵循 Android 的标准 ABI（应用程序二进制接口）命名约定：

ARM 架构支持 (armeabi-v7a)

ARM 架构是 Android 设备最常见的平台，特别是旧款和中端设备。该库支持多个为 32 位 ARM 指令集优化的 WebView 包。

支持的包包括：

• Google WebView（版本 122.0.6261.64）：从 com.google.android.webview_122.0.6261.64_armeabi-v7a.zip 远程下载
• Android WebView（版本 113.0.5672.136）：基于 AOSP 的替代版本
• Huawei WebView（版本 14.0.0.331）：制造商特定实现
• Chrome（版本 122.0.6261.43）：完整的 Chrome 浏览器包
• Amazon WebView Chromium（版本 118-5993-tv.5993.155.51）：Amazon Fire TV 和平板设备

ARM64 架构支持 (arm64-v8a)

现代高端 Android 设备主要使用 64 位 ARM 架构（AArch64）。该库提供了优化的 WebView 包，可充分利用 ARM64 处理器的增强性能能力。

对于 ARM64 设备，支持的包包括：

• Google WebView（版本 122.0.6261.64）：从 com.google.android.webview_122.0.6261.64_arm64-v8a.zip 获取的 64 位优化版本
• Huawei WebView（版本 14.0.0.331）：支持 ARM64 和 ARM 的双架构包

x86 架构支持

x86 架构虽然在消费级 Android 设备中不太常见，但对于模拟器开发和特定的基于 Intel 的硬件仍然至关重要。该库提供了为 x86 指令集编译的专用 WebView 包。

对于 x86 环境，可用选项包括：

• Google WebView（版本 122.0.6261.64）：从 com.google.android.webview_122.0.6261.64_x86.zip 网络下载
• Google WebView（版本 131.0.6778.105）：较新版本可作为嵌入式资源使用，特别适用于 Android 模拟器测试

x86_64 架构支持

64 位 x86 架构服务于高性能 x86 环境和现代模拟器。虽然设备采用率有限，但对 x86_64 的支持确保了与测试基础设施和专业硬件的兼容性。

目前，该库支持：

• Google WebView（版本 131.0.6778.135）：可从社区维护的存储库 x64.apk 获取的最新版本

版本和架构兼容性表

制造商特定注意事项

理解制造商 WebView 碎片化

Android 设备制造商对 WebView 内核的实现各不相同，形成了一个碎片化的生态系统，导致同一 Android 版本在不同设备上的 WebView 功能可能存在显著差异。这种碎片化直接影响功能可用性，尤其是对 H265 视频等现代媒体格式的支持。

常见制造商 WebView 包

不同制造商部署的 WebView 包具有不同的包命名约定和版本管理策略：

重要：仅凭制造商包名不能保证功能支持。始终检查 UserAgent 字符串中的实际 Chromium 版本，而不是依赖包版本号，因为报告的包版本与底层 Chromium 版本之间可能存在显著差异。

华为案例研究：H265 限制

华为设备是 WebView 内核升级最具说服力的用例之一。在实践中，华为的默认 WebView 实现（com.huawei.webview）经常落后于 Chromium 生态系统，特别是在 Google 移动服务（GMS）区域外运行的设备。

文档示例演示了一台运行 Android 12 的华为 Mate30，其系统 WebView 版本为 14.0.0.331，但 UserAgent 中的实际 Chromium 版本仅为 99.0.4844.88——远低于 H265 硬件加速播放所需的 Chromium 107 阈值。

这种版本限制迫使开发者采用不可取的变通方法，如基于 JavaScript 的 H265 解码，这会引入显著的性能开销和电池消耗。通过升级 WebView 内核，同一设备可以从制造商有限的实现过渡到 Google 的基于 Chrome 的 WebView（版本 122.0.6261.64，Chromium 122.0.6261.64），从而启用原生 H265 支持并显著提高视频播放性能。

Amazon Fire OS 注意事项

Amazon 设备由于 Fire OS 生态系统带来了独特挑战，该生态系统维护着自己独立的 WebView 基础设施，与标准 Android 生态系统分离。Amazon WebView 实现（com.amazon.webview.chromium）遵循 Amazon 的版本控制方案（例如 118-5993-tv.5993.155.51），而不是 Google 的 Chrome 版本号，这为版本检测和升级目标定位增加了额外的复杂性。

Amazon 的 WebView 管理方法对于针对 Fire TV 设备和 Fire 平板的开发者尤为重要，因为这些设备可能完全缺乏 Google Play 服务，并完全依赖 Amazon 专有的 WebView 分发。升级机制必须通过为 Amazon 设备提供特定架构的 APK 包来考虑这一点，特别关注主导 Amazon 硬件产品线的 ARMv8（arm64-v8a）和 ARMv7（armeabi-v7a）架构。

设备测试矩阵

制造商兼容性不能在没有跨设备类别实证测试的情况下假设。WebViewUpgrade 库已在以下设备矩阵上得到验证，代表了 Android 生态系统的横截面：

设备兼容性测试应优先考虑每个制造商的旧设备，因为它们更有可能运行过时的 WebView 实现。较新的旗舰设备通常默认附带更新的 WebView 版本，降低了内核升级的紧迫性。

免安装 APK 加载技术

架构概述

免安装加载 APK 技术代表了一种将 Android APK 动态加载为资源的复杂方法。该方法不依赖标准的 PackageManager 安装流程，而是从存储为资源或从远程来源下载的 APK 文件中提取 WebView 组件，然后直接将其加载到应用程序的 WebView 基础设施中。这种方法实现了运行时 WebView 升级，而无需设备级权限或干扰系统的 WebView 安装。

核心加载机制

APK 存储策略

该技术使用可预测的命名约定将 WebView APK 存储在应用程序的私有文件目录中：FilesDir/packageName/versionName.apk。这确保每个 WebView 版本都保持其独立的存储位置，同时仅对应用程序可访问。

资源配置

为支持内置 APK 资源，构建配置必须防止打包期间的 APK 压缩。这通过 aaptOptions 指令实现：

aaptOptions {
    noCompress "apk"
}

此配置确保作为资源嵌入的 APK 文件保持其原始结构，从而无需解压缩开销即可直接加载。

原生库集成

该技术需要原生库支持不同的设备架构。项目包含 ARM 和 ARM64 架构的原生库。

重要：免 APK 安装意味着该技术完全绕过了 Android 的验证和签名检查。虽然这提供了灵活性，但需要仔细验证 APK 来源以确保安全性和兼容性。

加载过程流程

完整的加载过程涉及几个不同的阶段，将 APK 文件转换为功能性的 WebView 内核：

1. APK 获取：从远程下载、资源提取或已安装包获取 APK
2. 文件验证：验证 APK 完整性和架构兼容性
3. Native 库提取：从 APK 中解压适当的共享库
4. ClassLoader 配置：配置自定义类加载器
5. 内核替换：替换系统 WebView 内核
6. 完成通知：触发成功回调

进程状态管理

升级机制通过一系列布尔检查维护进程状态，防止并发升级和动态切换：

技术优势和局限性

优势：

• 无需系统权限：绕过安装权限的需求
• 隔离性：升级的 WebView 不影响其他应用程序
• 回滚能力：通过停止使用轻松恢复到系统 WebView
• 版本控制：多个版本可以在应用程序目录中共存

局限性：

• 无动态切换：一旦升级，应用程序无法在不同 WebView 内核之间动态切换
• 内存开销：需要额外存储空间用于 APK 文件和提取的库
• 平台依赖性：依赖可能随版本变化的 Android 内部 API

UserAgent 版本检测与比较

UserAgent 字符串提取

WebView 的 UserAgent 字符串包含有关底层内核的详细信息，包括实际的 Chromium 版本号，该版本号可能与系统设置中显示的软件包版本显著不同。检索此字符串需要在初始化后访问 WebView 设置。

在演示实现中，UserAgent 在 WebView 创建后立即使用 WebSettings API 提取：

WebSettings webSettings = mWebView.getSettings();
userAgentTextView.setText(webSettings.getUserAgentString());

此 UserAgent 字符串遵循标准的 Chromium 格式，包含内核信息，例如 Chrome/122.0.6261.64，表示驱动 WebView 实例的实际 Chromium 版本。

软件包版本与 Chromium 版本

WebView 软件包版本与 UserAgent 中嵌入的 Chromium 版本之间存在关键区别。软件包版本遵循制造商的命名约定，而 Chromium 版本遵循 Google 的版本编号并决定功能可用性。

这种差异在华为设备上尤为明显，其系统 WebView 软件包 com.huawei.webview 显示版本 14.0.0.331，但 UserAgent 中的实际 Chromium 版本为 99.0.4844.88。此 Chromium 版本低于 107，而 107 是支持 H265 视频播放的最低要求。

系统 WebView 信息检索

WebViewUpgrade 库提供静态方法来查询当前安装的系统 WebView 软件包信息，而无需创建 WebView 实例：

String systemWebViewPackageName = WebViewUpgrade.getSystemWebViewPackageName();
String systemWebViewPackageVersion = WebViewUpgrade.getSystemWebViewPackageVersion();

版本比较与升级决策流程

升级过程涉及比较当前 WebView 的功能与功能要求。应用程序中演示的实际工作流程展示了版本信息如何指导升级决策：

1. 检查功能要求：确定所需的最低 Chromium 版本（如 H265 需要 107+）
2. 获取系统 WebView 软件包信息：查询当前包名和版本
3. 解析 UserAgent Chromium 版本：从 UserAgent 字符串中提取实际 Chromium 版本
4. 比较版本：判断当前版本是否满足要求
5. 选择升级目标：如果不满足，选择具有足够 Chromium 版本的目标包
6. 执行升级：启动升级过程
7. 升级后验证：验证 UserAgent 反映了正确的 Chromium 版本

升级后验证

完成升级过程后，验证至关重要，以确认预期版本已激活。演示应用程序的 WebViewActivity 通过显示升级后的 WebView 内核的 UserAgent 字符串来实现此目的。成功升级会显示软件包名称和 UserAgent 内容的变化——例如，从 com.huawei.webview（Chromium 99.x）升级到 com.google.android.webview（Chromium 122.x）。

重要：升级后始终验证 UserAgent 字符串，而不是仅依赖软件包版本信息，因为实际的内核功能由 UserAgent 中嵌入的 Chromium 版本决定。某些制造商可能将较新的 Chromium 版本与较旧的软件包版本打包，反之亦然。

进程管理与错误处理

升级进程状态管理

升级进程实现了一个有限状态机，包含三个主要状态，可在升级生命周期中的任何时间进行查询。这种状态管理方法能够实现精确的控制流，并防止升级操作期间出现竞态条件。

系统在整个升级过程中跟踪三种不同的状态：

• 处理中状态：升级正在进行中，防止并发升级操作
• 已完成状态：升级成功完成，为稳定性禁用进一步的升级尝试
• 失败状态：升级失败，捕获错误详情用于诊断

状态检查在 MainActivity 中演示，其中根据当前状态有条件地允许用户操作：

if (WebViewUpgrade.isProcessing()) {
    Toast.makeText(getApplicationContext(), "webView is being upgraded, please wait", Toast.LENGTH_LONG).show();
} else if (WebViewUpgrade.isCompleted()) {
    Toast.makeText(getApplicationContext(), "webView is already upgrade success, not support dynamic switch", Toast.LENGTH_LONG).show();
} else {
    // Proceed with upgrade
}

系统强制执行严格的单次升级策略。当 isProcessing() 返回 true 时，所有新的升级请求都会被拒绝，以防止资源冲突并确保升级过程中的数据完整性。

进度跟踪架构

进度监控以从 0.0 到 1.0 的连续百分比刻度运行，通过 UpgradeCallback 接口提供实时更新。进度跟踪系统为升级操作的每个阶段提供细粒度的可见性，从源准备到最终的 WebView 初始化。

错误处理和恢复

错误处理架构捕获全面的诊断信息，包括错误消息和完整的堆栈跟踪。这种方法既支持面向用户的错误通信，也支持开发人员级别的调试功能。

错误捕获和显示

当发生错误时，系统通过 Toast 通知提供即时用户反馈，并通过 UI 提供详细的错误信息：

@Override
public void onUpgradeError(Throwable throwable) {
    Toast.makeText(getApplicationContext(), "webView upgrade fail", Toast.LENGTH_SHORT).show();
    Log.e("MainActivity", "message:" + throwable.getMessage() + "\nstackTrace:" + Log.getStackTraceString(throwable));
    updateUpgradeWebViewStatus();
}

常见错误场景

升级操作期间遇到的最常见错误包括：

• 远程下载的网络连接故障
• APK 提取的存储空间不足
• 设备与提供的 APK 之间的架构不匹配
• 损坏或无效的 APK 文件
• 与签名验证或权限拒绝相关的安全异常

每个错误场景都通过 onUpgradeError(Throwable throwable) 回调提供特定的异常类型和消息。应用程序应解析这些异常以提供用户友好的错误消息，并在可行时实现适当的重试逻辑。

进程隔离和线程安全

升级系统强制执行进程隔离以防止并发升级尝试之间的冲突。isProcessing() 检查充当关键的同步点，确保在任何给定时间只能执行一个升级操作。

进程隔离机制防止了几种关键的故障场景：

• 资源冲突：防止多个下载线程写入同一文件路径
• WebView 不稳定：避免并发 WebView 初始化，这可能导致渲染器进程崩溃
• 内存压力：通过防止重叠的 APK 加载操作来限制内存使用

H265 视频播放实现

问题背景

H265 (HEVC) 视频播放是 WebViewUpgrade 库的一个关键用例，旨在解决 Android 设备上因系统 WebView 内核过时导致的兼容性问题。主要挑战出现在华为和亚马逊等设备制造商的设备上，这些设备的系统 WebView 的 Chromium 版本过旧，无法支持 H265 解码，需要通过内核升级来启用现代视频编解码器支持。

H265 视频播放问题出现在系统 WebView 内核的 Chromium 版本低于 107 的设备上。在华为设备上，默认系统 WebView 包 com.huawei.webview 的版本 14.0.0.331 在其 UserAgent 字符串中包含 Chromium 版本 99.0.4844.88，该版本早于 Chromium 107 中引入的 H265 支持实现。这种版本差距导致 WebView 无法原生播放 H265 视频，迫使开发者实现基于 JavaScript 的解码方案，从而引入显著的性能开销。

H265 支持阈值

支持 H265 播放的技术要求是 Chromium 版本 107 或更高。WebViewUpgrade 库通过启用将系统 WebView 替换为满足此要求的更新内核来解决这个问题。成功升级后，之前无法播放 H265 内容的设备通过升级后的 WebView 内核获得完整的原生支持。

WebView 包兼容性

不同的 WebView 包提供不同级别的 H265 支持：

H265 支持的升级配置

演示应用程序提供了配置支持 H265 的 WebView 升级的完整参考实现。配置包括特定于架构的包映射：

UPGRADE_PACKAGE_MAP.put("arm", Arrays.asList(new UpgradeInfo("com.google.android.webview", "122.0.6261.64", "https://mirror.ghproxy.com/.../com.google.android.webview_122.0.6261.64_armeabi-v7a.zip", "网络"), new UpgradeInfo("com.android.webview", "113.0.5672.136", "https://mirror.ghproxy.com/.../com.android.webview_113.0.5672.13_armeabi-v7a.zip", "网络")));

架构检测至关重要 - 应用程序使用 ProcessUtils.getCurrentInstruction() 自动选择适当的 WebView 包（arm64-v8a、armeabi-v7a、x86、x86_64），以确保与设备 CPU 架构的兼容性。

H265 视频测试实现

演示应用程序包含一个专用的测试活动用于验证 H265 播放功能。WebViewActivity 加载标准的 H265 测试视频 URL 以确认升级成功：

mWebView.loadUrl("https://test-videos.co.uk/bigbuckbunny/mp4-h265");

此实现演示了完整的工作流程：将 WebView 内核升级到 Chromium 版本 ≥107，然后加载 H265 内容以验证原生编解码器支持是否正常工作。

升级过程监控

升级过程通过 UpgradeCallback 接口实现全面的状态跟踪：

• onUpgradeProcess(float percent) - 报告下载/进度状态
• onUpgradeComplete() - 表示 WebView 升级成功
• onUpgradeError(Throwable throwable) - 报告升级失败

此监控对于确保在尝试 H265 视频播放之前升级成功完成至关重要。

验证和确认

升级后验证涉及检查 UserAgent 字符串中的包名和 Chromium 版本：

升级前：

• 包：com.huawei.webview
• UserAgent Chromium：99.0.4844.88

升级后：

• 包：com.google.android.webview
• UserAgent Chromium：122.0.6261.64

演示应用程序实时显示此信息，允许开发者确认已成功转换到支持 H265 的 WebView 内核。

支持的设备架构

H265 播放实现需要特定于架构的 WebView 包：

应用程序自动检测设备架构并呈现兼容的升级选项，确保所选的 WebView 包将与设备的 CPU 指令集兼容。

从系统 WebView 迁移至升级内核

了解迁移需求

现代 Android 设备在不同制造商之间存在严重的 WebView 碎片化问题。华为和亚马逊等制造商的系统 WebView 内核通常落后于 Google 的 Chromium 发布版本，导致尖端网络技术出现兼容性差距。例如，运行 WebView 内核版本 14.0.0.331（基于 Chromium 99.0.4844.88）的华为设备无法播放 H265 视频，这需要 Chromium 107 或更高版本。

迁移将你应用程序的 WebView 环境从系统提供的内核转变为嵌入应用程序的升级内核。此升级将 WebView 包名从制造商特定包（如 com.huawei.webview）更改为标准包（如 com.google.android.webview），同时更新 Chromium 版本以支持现代网络标准。

实施步骤

步骤 1：依赖配置

首先将 WebViewUpgrade 库添加到你的项目中：

dependencies {
    implementation 'io.github.jonanorman.android.webviewup:core:0.1.0'
    implementation 'io.github.jonanorman.android.webviewup:download-source:0.1.0'
}

步骤 2：选择升级源策略

根据你的应用程序需求和分发策略选择升级源。每种源类型适用于不同的使用场景：

步骤 3：初始化升级过程

在应用程序的启动或初始化阶段实施升级逻辑：

// 选项 1：从远程 URL 下载
UpgradeDownloadSource downloadSource = new UpgradeDownloadSource(
    context,
    "https://example.com/webview_122.0.6261.64_arm64-v8a.zip",
    new File(context.getFilesDir(), "webview_upgrade.apk")
);
// 选项 2：从应用资源加载
UpgradeAssetSource assetSource = new UpgradeAssetSource(
    context,
    "com.google.android.webview_122.0.6261.64_arm64-v8a.apk",
    new File(context.getFilesDir(), "webview_upgrade.apk")
);
// 选项 3：使用已安装的包
UpgradePackageSource packageSource = new UpgradePackageSource(
    context,
    "com.google.android.webview"
);
// 执行升级
WebViewUpgrade.upgrade(downloadSource); // 或 assetSource 或 packageSource

步骤 4：实施进度监控

注册升级回调以跟踪升级过程并向用户提供反馈：

public class MainActivity extends Activity implements UpgradeCallback {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        WebViewUpgrade.addUpgradeCallback(this);
    }

    @Override
    public void onUpgradeProcess(float percent) {
        // 更新进度条或 UI
        progressBar.setProgress((int) (percent * 100));
    }

    @Override
    public void onUpgradeComplete() {
        // WebView 现在已准备就绪，使用升级内核
        Toast.makeText(this, "WebView upgrade success", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onUpgradeError(Throwable throwable) {
        // 处理升级失败
        Log.e("WebViewUpgrade", "Upgrade failed", throwable);
        Toast.makeText(this, "WebView upgrade fail", Toast.LENGTH_SHORT).show();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        WebViewUpgrade.removeUpgradeCallback(this);
    }
}

步骤 5：验证升级成功

升级完成后，通过检查包名和版本信息来验证你的应用程序是否正在使用升级版 WebView 内核：

String systemPackage = WebViewUpgrade.getSystemWebViewPackageName();
String systemVersion = WebViewUpgrade.getSystemWebViewPackageVersion();

// 检查升级状态
if (WebViewUpgrade.isCompleted()) {
    Log.d("WebViewUpgrade", "Upgrade successful"); // WebView 现在使用升级内核
} else if (WebViewUpgrade.isFailed()) {
    Throwable error = WebViewUpgrade.getUpgradeError();
    Log.e("WebViewUpgrade", "Upgrade failed: " + error.getMessage());
}

// 监控升级进度
float progress = WebViewUpgrade.getUpgradeProcess();

你还可以通过检查 WebView 的 UserAgent 字符串来验证升级，成功迁移后该字符串应反映新的 Chromium 版本。

架构比较

迁移从根本上改变了你的应用程序与 WebView 渲染引擎的交互方式：

迁移检查清单

在部署带有升级版 WebView 的应用程序之前，确保你已完成这些步骤：

• 将 core 和 download-source 依赖项添加到 build.gradle
• 为你的用例选择合适的升级源策略
• 在应用程序启动中实施升级初始化
• 添加用于进度监控的升级回调
• 创建用于升级状态和控制的用户界面
• 使用目标功能（H265 等）测试升级版 WebView 功能
• 验证 UserAgent 反映了正确的 Chromium 版本
• 适当处理错误场景和网络故障
• 如果使用 UpgradeAssetSource，配置 APK 资源
• 在目标设备架构（ARM、ARM64、x86、x86_64）上测试

多架构支持策略

架构检测机制

多架构支持的基础在于自动检测设备当前的指令集架构。该库使用 ProcessUtils.getCurrentInstruction() 来确定适合当前运行时环境的 WebView 包。

架构检测遵循 Android 的标准 ABI（应用程序二进制接口）命名约定。检测方法将 Android ABI 名称映射为简化的架构标识符：armeabi 和 armeabi-v7a 映射为 "arm"，arm64-v8a 映射为 "arm64"，而 x86 和 x86_64 保持不变。这种方法确保了在所有 Android API 级别上的兼容性，包括那些现代架构检测 API 可能不可用的旧设备。

架构特定包映射

该库采用集中化映射策略，将每个支持的架构与精选的兼容 WebView 升级包列表相关联。此映射通过静态数据结构实现，其中每个架构键对应一个包含包元数据的 UpgradeInfo 对象数组。

ARM 架构（armeabi-v7a）

提供最广泛的选择，包括 Google WebView 122.0.6261.64、Android WebView 113.0.5672.136、华为 WebView 14.0.0.331、Chrome 122.0.6261.43 和 Amazon WebView 118-5993-tv.5993.155.51。该架构受益于多种来源选项，包括网络下载、内置资源和已安装包检测。

ARM64 架构（arm64-v8a）

专注于现代 WebView 实现，包括 Google WebView 122.0.6261.64 和华为 WebView 14.0.0.331。ARM64 映射展示了该库对跨 ARM 和 ARM64 架构的统一包的支持。

x86 架构

主要针对 Google WebView，版本包括 122.0.6261.64 和 131.0.6778.105，支持网络下载和内置资源部署策略。x86 架构的嵌入式资源方法对开发工作流程特别有价值。

x86_64 架构

提供对 Google WebView 131.0.6778.135 的访问，展示了该库对 64 位 x86 设备的支持，这些设备在模拟环境和某些基于 Intel 的 Android 设备中很常见。

架构选择工作流

架构选择过程遵循一个确定性工作流，从应用程序初始化开始，最终完成 WebView 内核加载。过程首先使用 ProcessUtils.getCurrentInstruction() 方法进行架构检测，该方法会缓存结果以避免重复的系统调用。一旦识别出架构，该库会从架构映射中检索相应的升级包列表。然后用户或应用程序逻辑可以根据版本要求、源类型偏好或供应商特定考虑等因素从可用选项中进行选择。

实现最佳实践

实现多架构支持需要仔细考虑几个因素，以确保在所有设备类型上的行为一致：

1. 资源组织：使用内置 APK 源时，保持清晰的目录结构，按架构分离 APK 文件
2. 回退策略：并非所有架构都可能为每个版本或供应商提供 WebView 包。实现回退逻辑，通过选择替代包或向用户提供信息性错误消息来优雅处理架构特定的不可用性
3. 测试矩阵：对所有支持的架构进行全面测试至关重要
4. 包大小优化：包含多个架构的 APK 文件会显著增加应用程序大小。考虑通过 Google Play 的多 APK 支持提供架构特定的 APK 变体，或实现即时下载策略，在安装后根据设备架构检索适当的 APK

架构兼容性矩阵

兼容性与测试

支持的平台和兼容性

WebViewUpgrade 已在多种设备制造商和 WebView 实现上进行了测试：

WebView 包支持

测试设备型号

该库支持 Android 5.0（API 级别 21）及以上，核心模块的最低 SDK 为 21，目标 SDK 为 33。

架构特定升级包

系统支持以下 CPU 架构：

• ARM 64 位 (arm64-v8a)
• ARM 32 位 (armeabi-v7a)
• Intel x86 (x86)
• Intel x86_64 (x86_64)

应用程序需要为每个架构提供相应的 WebView APK 包，库会自动检测设备架构并选择兼容的包。

制造商特定注意事项

华为设备

华为设备通常使用 com.huawei.webview，其 Chromium 版本可能较旧。WebViewUpgrade 可以将其升级到 Google WebView 以支持现代 Web 标准。

亚马逊设备

Amazon Fire TV 设备使用 com.amazon.webview.chromium，WebViewUpgrade 也支持升级这些设备。

最佳实践

升级时机

关键限制：必须在任何 WebView 实例化之前完成升级与切换，否则容易出现 UnsatisfiedLinkError: Shared library already opened 等链接错误。

推荐位置：在 Application.onCreate() 的最早时机执行升级。

错误处理

实现完善的错误处理机制：

@Override
public void onUpgradeError(Throwable throwable) {
    Log.e("Upgrade", "升级失败", throwable);
    // 根据错误类型采取不同策略
    if (throwable instanceof IOException) {
        // 网络错误，可以重试
    } else if (throwable instanceof SecurityException) {
        // 权限问题，提示用户
    } else {
        // 其他错误，降级处理
    }
}

版本检测

在升级前检查当前版本，避免不必要的升级：

String currentPackage = WebViewUpgrade.getSystemWebViewPackageName();
String currentVersion = WebViewUpgrade.getSystemWebViewPackageVersion();
if (needsUpgrade(currentPackage, currentVersion)) {
    // 执行升级
} else {
    // 已满足要求，跳过升级
}

文件管理

• 使用应用程序私有目录存储下载的 APK
• 按包名和版本组织文件结构
• 定期清理旧的升级文件以节省存储空间

用户体验

• 在升级过程中显示进度条
• 提供清晰的错误提示
• 允许用户取消或重试失败的升级
• 在升级完成后提供明确的成功反馈

性能优化

• 对于大型 APK 下载，考虑使用后台服务
• 实现断点续传功能（Aria 库支持）
• 缓存已下载的 APK 以避免重复下载

安全考虑

• 验证下载的 APK 的完整性
• 使用 HTTPS 下载源
• 检查 APK 签名（如果可能）

总结

WebViewUpgrade 库为 Android 开发者提供了一个强大的解决方案，用于解决 WebView 内核碎片化和兼容性问题。通过免安装升级机制，应用程序可以在不依赖系统更新的情况下，为所有用户提供一致的现代 Web 体验。

核心优势

1. 免安装升级：无需用户权限，即时切换 WebView 内核
2. 多种升级源：支持远程下载、内置资源和已安装包
3. 架构感知：自动处理不同 CPU 架构
4. 跨厂商兼容：支持华为、小米、Vivo、Oppo、亚马逊等设备
5. 简单易用：提供简洁的 API 和完整的回调系统

适用场景

• 需要 H265 视频播放支持
• 需要现代 Web 标准支持（ES6+、WebCodecs 等）
• 需要统一的 WebView 体验，不受设备制造商限制
• 无法依赖 Google Play 更新的场景

注意事项

• 必须在 WebView 首次初始化前完成升级
• 当前不支持多进程和动态切换
• 需要为不同架构提供相应的 APK 包
• 部分厂商设备可能有特殊限制