Capacitor Android 运行时演进全景：从 8.4.2 回溯 5 代版本的核心修复与特性速览

导读

本文基于当前仓库 android/CHANGELOG.md 整理，系统梳理 Capacitor Android 运行时从 8.4.2 回溯至 3.0.0 期间各版本的关键变更。全文以「Bug Fixes / Features」双主线展开，覆盖系统栏（SystemBars）与安全区适配、Capacitor Http 网络栈、WebView 生命周期、插件权限体系、Gradle/AGP 构建链、本地资源服务器等核心模块，并逐一映射到 android/capacitor 下的源码与配置，帮助升级排障、特性选型与源码深挖。

说明：按 2025-12 的 8.0 大版本发布节奏，8.4.x 为当前仓库最新维护线；「Note: Version bump only」条目表示仅随 monorepo 版本号发布，无 Android 侧实质变更。

一、8.x 时代（2025–2026）：SystemBars 与 Edge-to-Edge 全面落地

8.x 是 Android 运行时向 Edge-to-Edge（全面屏沉浸式）规范迁移的关键时期，绝大多数提交围绕「系统栏样式、安全区 inset、键盘与刘海屏」展开。

1.1 SystemBars 插件成为一等公民

• 8.0.0-beta.0（2025-11）正式引入 System Bars Plugin（PR #8180），随后 8.0.0 的 Improving SystemBars inset handling（PR #8268）完善其 inset 计算。该插件在源码中为 android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java 中的 SystemBars extends Plugin，通过 WindowInsetsControllerCompat 控制状态栏/手势导航栏的显隐与明暗，并注入 --safe-area-inset-* CSS 变量。
• 8.3.0 起改用原生安全区 inset（PR #8384），并在 8.4.0 使 safe-area-inset-x 在 API ≤ 34 也可用（PR #8424）、尊重 insetsHandling: disable（PR #8481）、只显示被请求的系统栏（PR #8480）。

1.2 安全区与键盘协同处理

• 7.1.0 增加 adjustMarginsForEdgeToEdge 配置（PR #7885）与 EdgeToEdge 兼容（PR #7871）。
• 8.0.1 修复「键盘弹出时底部 inset 被误加」问题（PR #8280）；8.1.0 修复 handleOnConfigurationChanged 下样式获取错误（PR #8295）；8.2.0 修复固定 WebView 时跳过 margin 操作（PR #8309）、按主题设置窗口背景色（PR #8306）。
• 实现要点：calcSafeAreaInsets 在 IME 可见时强制 bottom=0，并在 WebView 版本 ≥140/144 时启用 Chromium 安全区/键盘修复分支（见 SystemBars.java L41-L43）。

1.3 网络与配置补充

• 8.4.0 新增 PluginCall.getDouble（PR #7638，见 PluginCall.java L233）。
• 8.3.0 修复 server.url 含路径时的解析（PR #8391）、fetch 处理 URL 对象（PR #8386）。
• 8.0.2 修复 AGP 9.0 不再支持 proguard-android.txt 的构建链问题（PR #8315）；8.4.2 修复图片捕获 Intent 的 URI 权限显式授予（PR #8526）。

二、7.x 时代（2024–2025）：Edge-to-Edge 过渡与 WebView 生命周期

• 7.1.0 加入「文档加载前向 WebView 注入外部 JS」能力（PR #7864，对应 WebViewListener / JSInjector）。
• 7.0.0-beta.0 引入全局 initialFocus 配置（PR #7775），最终落位于 android.initialFocus（CapConfig.java L306）。
• 7.3.0 暴露 appStartPath（PR #8019）并在 bridge reset 时移除全部插件监听器（PR #7962）；7.4.2 修复 HTTP x-www-form-urlencoded 的 key/value URL 编码（PR #8037）。

三、6.x 时代（2023–2024）：Http 代理走向成熟

• 6.1.0 起 server.url 结尾 / 不再崩溃（PR #7426）。
• 6.0.0-rc.x 密集修复 Http 代理：URL 参数编码（#6586）、代理 URL 端口（#7273、#7341）、Request 对象代理（#7348）、keep 原始 URL 属性（#7329）、GET 走自定义 handler（#6818）、错误处理交给 WebView（#7286）、URLSearchParams 支持（#7374）、POST 不被代理（#7395）。
• 6.0.0-alpha.x 增加 FormData 写入、Request 对象支持（#6919、#7001、#24b3cc1）、content-type 计数修复（#7161）、本地 URL 使用未打补丁的 fetch（#6953）、ReadableStream 解析（#6919）。
• 6.0.0-beta.0 起支持 Amazon Fire WebView（#6603）。

四、5.x 时代（2023）：FormData、Cookies 与 R8/ProGuard 修复

• 5.2.0 正式支持 FormData 请求（#6708）；5.4.0 支持 fetch 的 Request 对象与 XHR 响应类型（#09bd040、#2fe4535）；5.5.0/6.0.0-alpha.1 提供 onRenderProcessGone 自定义逻辑（#6946、#6966，见 WebViewListener.java L53）。
• Cookies：5.2.0 前 sanitize URL（#ca40634）、5.2.3 隐藏 httpOnly cookies（#0cc927e）、5.3.0 初始化时移除会话 cookie（#037863b）、5.4.1 支持自定义 Android scheme 取 cookie（#6b5ddad）。
• R8/ProGuard：5.2.3 修复 R8 移除插件类（#6783），规则见 android/capacitor/proguard-rules.pro（-keep @com.getcapacitor.annotation.CapacitorPlugin public class *）。
• 5.1.0 增加 SSL 排除域检查（#7906d36）；5.0.0-beta.3 升级 Gradle 8.0.2 / AGP 8.0.0（#6497）。

五、4.x 时代（2022）：Config 重构与 Plugin 基础设施

• 4.7.0：Config 自定义文件路径（#6264）、SSL Pinning（#6314）、加载 content 目录外资源（#6301）。
• 4.6.0：Plugin Instance 支持（#6073）、Set-Cookie 持久化（#57f8b39）。
• 4.5.0：旧版 addJavascriptInterface bridge 开关（#6043，对应 android.useLegacyBridge）、Cookies get cookies 方法（#ba1e770）。
• 4.4.0：ServerPath 对象（#6008）、document.cookie setter 同步化（#2272abf）。
• 4.3.0：Capacitor Cookies & Capacitor Http 核心插件正式引入（#d4047cf）。
• 4.0.0：android.minWebviewVersion（#5768）、自定义错误页（#5723）、addWebMessageListener 优先（#5427）、目标 SDK 31/32（#5442/#5611）、Java 11（#5552）。

六、3.x 时代（2021–2022）：权限体系与 Config 奠基

• 3.0.0-alpha.x：插件注解格式支持多权限/空权限（#3822）、handlePermissions（#3768）、按 alias 检查权限（#4062）、CapConfig.loadDefault() 并废弃 v2 构造器（#3964）、WebColor 颜色解析（#3947）、配置重构（#3778）、onConfigurationChanged 生命周期钩子（#3936）、自动导入 Android 插件（#3788）。
• 3.4.0：PluginCall.getLong（#5235）；3.3.0：WebView 重载能力（#5184）；3.2.0：不注入 map 文件（#4893）。

七、升级与排障速查

• 构建链：minSdkVersion=24（8.0.0-alpha.1 起，见 android-template/variables.gradle L2），当前模板 compile/targetSdk=36，AGP 需 ≥9.0 兼容（8.0.2）。库验证命令：./gradlew clean lint build test -b capacitor/build.gradle（见 android/package.json L23）。
• 降级/白屏：检查 SystemBars insetsHandling（css/disable）与 viewport viewport-fit=cover；Http 代理请关注 6.0.0-rc.1 的 URL 参数编码修复。
• 插件消失：核对 ProGuard keep 规则是否匹配 proguard-rules.pro。

附：版本时间线（Android 侧）

版本	时间	主题
8.4.2	2026-07	URI 权限修复
8.4.0	2026-06	SystemBars inset 完善、getDouble
8.3.x	2026-03~05	原生安全区 inset、server.url 解析
8.0.0	2025-12	SystemBars inset 重构
7.4.x	2025-06~07	appStartPath、displayCutout
7.0.0	2025-01	initialFocus
6.1.x	2024-06~08	URL 编码、FormData 旧设备
6.0.0	2024-04	Http 代理成熟、Fire WebView
5.6.0	2023-12	Fire WebView 支持
5.2.0	2023-07	FormData 支持
4.7.0	2023-02	SSL Pinning、Config 路径
4.3.0	2022-09	Cookies & Http 核心插件
3.3.0	2021-11	WebView 重载、getLong

全部条目均为本仓库 android/CHANGELOG.md 原文所载；各源码路径对应当前 8.4.2 分支实现，版本与行为随时间演进，请以你所使用版本的实际源码为准。