移动开发跨平台插件系统前端【免费下载链接】capacitorBuild cross-platform Native Progressive Web Apps for iOS, Android, and the Web ⚡️项目地址https://gitcode.com/gh_mirrors/ca/capacitor点击查看免费下载本文以 Capacitor 仓库中 core/CHANGELOG.md 为脉络完整梳理capacitor/core从 v3.0.0-alpha.02020 年 7 月到 v8.4.22026 年 7 月的版本演进史并对照当前仓库中 core/src 下的运行时源码逐一印证每次变更背后的实现细节。读完本文你将掌握 Capacitor 核心包插件注册 → 原生桥接 → 内置插件的演进主线理解 Cookies、Http、SystemBars 等内置核心插件的能力边界与配置选项并能据此判断在升级 Capacitor 主版本时哪些 API 会直接影响你的业务代码。一、为什么capacitor/core的 CHANGELOG 值得单独解读capacitor/core是 Capacitor 跨平台运行时的心脏它在 Web 端定义Capacitor全局对象、插件注册机制、Web 插件基类与异常体系并通过 native-bridge 与 iOSWKWebView message handler和 AndroidWebView addJavascriptInterface / addWebMessageListener两端桥接。仓库根目录的 CHANGELOG.md 记录的是整个 monorepocore、cli、android、ios 等的变更而 core/CHANGELOG.md 则单独追踪 core 包的发布历史其中大量条目标注着 Version bump only for package capacitor/core——这意味着该版本对 core 而言只是随主版本号同步发布的版本号提升并未引入任何 JavaScript 运行时的行为变化。读懂这两类条目的区别是判断升级是否会影响我的前端代码的第一步。从仓库根目录的 lerna.json 和 package.json 可以看出Capacitor 采用 monorepo 与 lerna 管理多包发布每个包的 CHANGELOG 遵循 Conventional Commits 规范生成文档开头即注明 See Conventional Commits for commit guidelines因此正文按语义化版本分段每段包含 Features、Bug Fixes 或版本说明三类条目。二、v3.0核心运行时奠基期2020-07 ~ 2021-05v3 是capacitor/core从旧架构全面重写为今日形态的关键时期绝大多数今天开发者仍在使用的 API 都诞生于此。1.registerPlugin统一的插件注册入口v3.0.0-alpha.02020-07-23引入registerPlugin用于从插件包导入插件对应 PR #3305。这一 API 从此成为所有 Capacitor 插件的前端入口。在 core/src/global.ts 中可以看到它是Capacitor.registerPlugin的别名导出而真正的实现位于 core/src/runtime.ts每个插件通过registerPlugin(pluginName, jsImplementations)注册其中jsImplementations按平台android/ios/web提供 JS 实现或返回实现的工厂函数注册后的插件通过 ES6Proxy包装方法调用时先根据当前平台懒加载 JS 实现loadPluginImplementation若检测到原生PluginHeader则直接转调cap.nativePromise/cap.nativeCallback走原生桥若两者都不可用则抛出CapacitorExceptioncode 为UNIMPLEMENTED同一插件重复注册会被拦截并告警返回已注册的 proxy。runtime.ts中的getPlatformId逻辑在 core/src/util.ts检测window.androidBridge判定 Android、window.webkit.messageHandlers.bridge判定 iOS否则回落为 web。2. 权限体系与统一错误码v3.0.0-alpha.62020-10-30做了两件影响深远的事improve permissions与unified errors and error codes对应 PR #3673。统一错误码的实现即 core/src/util.ts 中的ExceptionCode枚举UNIMPLEMENTED/UNAVAILABLE与CapacitorException类Capacitor.Exception也被挂载到全局对象上runtime.ts。v3.0.0-alpha.72020-12-02进一步将PermissionState作为公开类型导出PR #3775其定义见 core/src/definitions.tsprompt | prompt-with-rationale | granted | denied这是所有 Capacitor 插件权限 API 的标准返回形态。3. 平台 API 与自定义平台支持v3.0.0-rc.22021-05-07引入platforms apiPR #4255随后 v3.0.0-rc.1 补充了优先调用原生实现、无原生实现时回退 Web 监听器的调度语义PR #4493、#4488。v3.2.02021-08-18实现CapacitorCustomPlatform支持第三方自定义平台PR #4771——这正是 core/src/runtime.ts 中capCustomPlatform的作用当检测到window.CapacitorCustomPlatform时getPlatform()直接返回自定义平台名插件加载逻辑也会优先命中该平台对应的实现。4. 其他 v3 关键修复v3.0.0-rc.1Unify logging behavior across environmentsPR #4416统一了多环境下的日志行为v3.0.0-rc.2安全地 JSON.stringify 循环引用对象PR #4507防止日志崩溃——对应 core/src/util.ts 中的 safeStringify 相关工具逻辑v3.0.0-beta.1修复 React 场景下的$$typeof报错PR #4013、#4113——这正是 runtime.ts 中 Proxy 对$$typeof与toJSON特殊处理的原因注释直接引用了 React issue #20030v3.0.0-beta.0add commonjs output formatPR #4064capacitor/core开始同时产出 ESM 与 CJS 两种格式对应 core/package.json 中的main与module字段v3.5.1cordova bridge 改用 Promise 替代 setTimeoutPR #5586提升 Cordova 兼容层的事件时序确定性v3.3.0避免日志循环对象崩溃PR #5186v3.1.2处理插件对象中的toJSON()PR #4823允许 safeStringify 支持多个 null 值PR #4853。三、v4.0Cookies 与 Http 两大内置插件诞生2021-08 ~ 2022-07v4.3.02022-09-21的 Capacitor Cookies Capacitor Http core plugins 是 core 包历史上最重要的功能性里程碑之一从此capacitor/core不再只是桥接层还内置了可直接使用的原生能力插件。它们的前端定义与 Web 实现都在 core/src/core-plugins.ts 中CapacitorCookiesL36-L154提供getCookies、setCookie、deleteCookie、clearCookies、clearAllCookies五个方法。Web 实现CapacitorCookiesPluginWeb直接读写document.cookie并使用类似 js-cookie 的encode/decode工具函数做安全转义原生侧则由 android/capacitor/src/main/java/com/getcapacitor/plugin/CapacitorCookies.java 与 ios/Capacitor/Capacitor/Plugins/CapacitorCookies.swift 实现。随后的 v4.5.0 增加了get cookies插件方法PR #ba1e770v4.4.0 将document.cookie的 setter 改为同步执行v4.6.0 改用Set-Cookie响应头持久化 cookie。CapacitorHttpL158-L494提供request/get/post/put/patch/delete六个方法。HttpOptions支持url、method、params、data、headers、readTimeout、connectTimeout、disableRedirects、responseType、shouldEncodeUrlParams、dataType、webFetchExtra等字段HttpResponse返回data、status、headers、url。Web 实现CapacitorHttpPluginWeb基于window.fetch构建请求并通过buildRequestInitL354-L396依据 Content-Type 自动处理字符串、x-www-form-urlencoded、FormData、JSON 四种请求体形态原生侧实现在 android/.../plugin/CapacitorHttp.java 与 ios/Capacitor/Capacitor/Plugins/CapacitorHttp.swift。与这两个插件配套的还有 core/cookies.md 与 core/http.md由 docgen 工具从CapacitorCookiesPlugin/CapacitorHttpPlugin接口自动生成见 core/package.json 的 docgen 脚本。v4.0.0 还包含若干 core 侧之外但影响 JS 侧的变更Android 端为 Error 对象增加可选 data 参数PR #5719、在可用时改用addWebMessageListenerPR #5427等。四、v5.0HTTP 能力持续增强期2022-11 ~ 2023-05v5 系列几乎每个带内容的版本都在强化 Http 插件的 Web 兼容性v5.1.0导出buildRequestInit函数供 downloadFile 等场景复用对应 core/src/core-plugins.ts 的公开导出v5.2.0支持FormData 请求PR #6708实现逻辑见buildRequestInit中multipart/form-data分支——将 FormData 交给window.fetch时删除手动设置的content-type让浏览器自动附加 boundaryv5.4.0为 fetch 增加Request 对象支持、为 XHR 与 Angular http 增加 responseType 支持、让window.XMLHttpRequest继承对象属性PR #2fe4535、#09bd040、#5cd3b2fv5.6.0当 content-type 未显式设置时正确设置 formdata 的 boundary 与请求体PR #7133修复项还包括content-type 为 null 时不再抛错v5.0.5、XHR 事件按正确顺序触发v5.2.0、相对 URL 的 XHR 请求返回有效响应v5.2.3、204 响应处理v5.0.0-beta.0、application/json时数字与布尔值原样返回v5.3.0等。v5.0.0-beta.0 还引入了retain multiple calls per event until consumedPR #6419这一事件保留机制的 Web 侧实现在 core/src/web-plugin.ts 的notifyListeners(eventName, data, retainUntilConsumed)中当某个事件尚无监听器且retainUntilConsumed为 true 时事件参数被暂存到retainedEventArguments待第一个监听器注册后通过sendRetainedArgumentsForEvent补发。五、v6.0代理 URL 与 Web 端事件机制完善2023-06 ~ 2024-04v6 系列的重点是 Http 代理机制的健壮性修复与 Web 事件 API 的补齐代理 URL 生成规则重构v6.0.0-rc.2 改变 proxy url 生成方式PR #7354rc.1 连续修复代理 URL 带端口#7273、保留原始 URL 属性#7329、代理支持 Request 对象#7348、GET 请求走自定义 handler#6818等问题v6.1.2 将原始 URL 作为 query 参数传给代理 URLPR #7527v6.0.0增加URLSearchParams 支持PR #7374禁止 POST 请求走代理PR #7395避免破坏原生请求语义v6.0.0-rc.0Web 端实现notifyListeners的retainUntilConsumedPR #7127即上节所述机制在 core 包层面的正式落地v6.0.0-rc.1WebView 插件新增setServerAssetPath方法见 core-plugins.ts 中WebViewPlugin接口定义与setServerBasePath/getServerBasePath/persistServerBasePath并列用于运行时切换本地资源目录其他修复v6.1.1 处理请求体中的UInt8ArrayPR #7546、v6.0.0-beta.0 解析 fetch Request 对象中的 ReadableStream 数据等。六、v7.0细节修复与兼容性收敛2024-08 ~ 2025-03v7 的 core 变更以精准的小修复为主v7.1.0cordova.js 中改用getPlatform替代platformPR #7902修复 Request 对象未添加 boundary 的问题PR #7897v7.2.0Http 请求支持应用overrideUserAgentPR #7906让原生请求携带与 WebView 一致的 UAv7.3.0Prevent error when hasListeners is emptyPR #7975加固 Web 插件事件系统——对应 core/src/web-plugin.ts 中hasListeners对空数组的容错处理v7.0.0-alpha.1 还向 iOS 暴露了CAPPluginCall.methodNamePR #7641等桥接增强。七、v8.0SystemBars 系统栏插件与 inset 处理2025-08 ~ 2026-07v8 是最近一个大版本core 侧最大的新增能力是System Bars Pluginv8.0.0-beta.0PR #8180——一个控制状态栏与导航栏样式和可见性的内置核心插件。其完整类型定义与 Web 占位实现在 core/src/core-plugins.tsSystemBarsStyleDARK深色背景下的浅色系统栏内容、LIGHT浅色背景下的深色内容、DEFAULT跟随设备外观SystemBarTypeStatusBar与NavigationBariOS 上即手势条方法setStyle(options)、show(options?)、hide(options?)、setAnimation(options)动画仅 iOS 支持FADE/NONEWeb 端实现SystemBarsPluginWeb对所有方法直接抛unavailable(not available for web)L639-L655因为系统栏控制只存在于原生环境。围绕 SystemBarsv8 后续版本做了大量 Android inset 打磨v8.0.0 的 Improving SystemBars inset handlingPR #8268、v8.0.2 将 hide/show 的 options 改为可选PR #8305并修复配置变更时的样式读取与主题背景色、v8.3.0 使用 Android 原生安全区 insetPR #8384、v8.4.0 让safe-area-inset-x在 API 34 也可用并尊重insetsHandling禁用项。这些能力在 Android 侧的实现在 android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.javaiOS 侧在 ios/Capacitor/Capacitor/Plugins/SystemBars.swift配套 API 文档见 core/system-bars.md。v8 中 core 的另外两处重要修复v8.3.0 让 fetch 正确处理 URL 对象PR #8386即把URL实例作为 fetch 输入时不再因 string 转换而丢失信息v8.1.0 仅在设置了日期时才向 Web 端发送 expires 参数b10cd7f避免无过期时间的 cookie 被错误序列化。八、如何结合源码阅读这份 CHANGELOG先看包结构core 包的入口导出集中在 core/src/index.ts导出Capacitor、registerPlugin、WebPlugin、CapacitorException、ExceptionCode及各类型运行时三件套分别是 global.ts全局对象初始化、runtime.ts插件注册与桥接调度、web-plugin.tsWeb 插件基类与事件系统。内置插件看 core-plugins.tsCookies、Http、WebView、SystemBars 四个内置插件的接口、选项类型与 Web 实现全部集中于此CHANGELOG 中每一条**http:**、**cookies:**、**SystemBars:**条目几乎都能在这里找到对应代码。测试佐证core 包的 jest 测试位于 core/src/tests如 plugin.spec.ts、bridge.spec.ts、web-plugin.spec.ts可用来验证 CHANGELOG 中声明的行为Android 端 Http 处理器的单测在 android/capacitor/src/test/java/com/getcapacitor/plugin/util/HttpRequestHandlerTest.java。版本节奏判断当某版本标注 Version bump only for package capacitor/core如 8.4.2、8.4.1、8.2.0、7.4.2 等说明该次发布对 core 无代码变更升级它不会引入 JS 层行为变化真正需要关注的是带 Features / Bug Fixes 条目的版本尤其是 v3.0、v4.3、v8.0 这类跨版本的功能里程碑。九、升级建议与核心要点回顾若你在业务代码中使用registerPlugin/WebPlugin/Capacitor.Exception等运行时 APIv3 之后这些 API 保持稳定v4 可直接升级若你依赖 Cookie 读写或希望请求走原生网络栈从 v4.3.0 起可使用内置CapacitorCookies/CapacitorHttp需要浏览器级 fetch/XHR 被自动接管时可在配置中启用CapacitorHttp并配合 patchedwindow.fetch/XMLHttpRequest其实现分布在 core 的 http.md 与 Android/iOS 原生模块中若你需要控制状态栏/导航栏外观v8 的SystemBars插件是标准入口注意其 Web 端不可用且 hide/show 的 options 均为可选升级前对照 core/CHANGELOG.md 中的**core:**、**http:**、**cookies:**前缀条目逐条评估再结合 core/src 源码确认行为差异即可将升级风险控制在最小范围。赞分享移动开发跨平台插件系统前端【免费下载链接】capacitorBuild cross-platform Native Progressive Web Apps for iOS, Android, and the Web ⚡️项目地址https://gitcode.com/gh_mirrors/ca/capacitor点击查看免费下载相关推荐Capacitor 版本演进全解析从 CHANGELOG 读懂 8.x 跨平台运行时架构与迁移要点Capacitor 版本演进全解析从 CHANGELOG 读懂 8.x 跨平台运行时架构与迁移要点 本文以 CHANGELOG.md https://link移动开发跨平台插件系统前端Arrow 发布历史全览从 0.1.5 到 1.4.0 的版本演进与核心 API 深度解读Arrow 发布历史全览从 0.1.5 到 1.4.0 的版本演进与核心 API 深度解读 Arrow Better dates times for P后端just 命令执行器版本演进全览从 CHANGELOG 解读 1.58.0 的核心能力just 命令执行器版本演进全览从 CHANGELOG 解读 1.58.0 的核心能力 本文以仓库根目录下的 CHANGELOG.md https://linCLI开发工具任务调度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考