跳转至正文

Capgo version_build 与 version_name:设置步骤

了解 Capgo 中 version_build 与 version_name 的工作原理、各自的值来自哪里,以及如何在发布 bundle 前检查 OTA 资格。

Capacitor native app baseline 与已下载的 Capgo bundle 示意图。

Capgo的版本名称起初可能会让人感到困惑: version_build 是原生应用的基准版本,而 version_name 则用于追踪设备上的 bundle。理清这两者的区别,你就能在正式发布前,判断设备为何能够或无法接收 OTA 更新。

我们分析了包括我们在内的 5 个 Live Update 平台的故障排除页面,发现我们的文档列出了 7 种具名的 version_build 不匹配错误代码,而其他四个平台分别只有 5、2、2 和 0 种。具名代码越多,出现 version_build 不匹配时就越少靠猜。

目录

  • 第 1 步:在 Capgo 中找到 version_build 和 version_name
  • 第 2 步:确定原生基线版本和已下载的 bundle
  • 步骤 3:检查原生 App 版本的来源
  • 第 4 步:设置并验证 Capgo 接收到的 bundle 版本
  • 第 5 步:发布更新前测试 channel 资格
  • 第 6 步:诊断版本不匹配并让发布可重复
  • 常见问题
  • 总结

第 1 步:在 Capgo 中找到 version_build 和 version_name

首先,把它们视为同一次应用安装的两个不同事实。 version_build 告知 Capgo 设备上运行的是哪个原生 App 版本。 version_name 告知 Capgo 设备下载了哪个 JavaScript bundle。两者的值可以不同,这通常是预期内的。

在 Capgo 的版本模型中,Native 版本是判断更新资格的基准。Capgo 会将分配给 Channel 的 Bundle 与该 Native 基准进行对比。设备上已安装的 Bundle 版本有助于识别其当前 Web code,但它并不能替代 Channel 的版本规则中的 Native 基准。

在排查问题前,请先在 Capgo 控制台的 Devices 页面查找设备并记录这两个值。然后将其与 Channel 的目标 Bundle 进行对比。 Capgo Channel 规则 说明 Channel 的目标版本如何与以下内容核对: version_build.

值 含义 用于回答 常见来源
version_build 发送到 Capgo 的 Native App 基准版本 这个 Native App 能否接收该 Channel 的目标 Bundle? Native App 版本,或显式的 Capacitor 配置值
version_name 当前已下载的 JavaScript Bundle 当前安装的是哪个 bundle 版本? 上传时解析出的 bundle 版本
Channel 目标版本 分配给设备 Channel 的 bundle Capgo 正在检查哪个版本的更新? 当前 Channel 分配情况

在发布说明或测试报告中,请将这三个值分列显示。如果团队只写一个笼统的“app version”,就很容易比错对象。判断更新资格时,请将目标 bundle 与 version_build进行对比。对于已安装的 web code,请检查 version_name.

Capgo 的命名方式可能看起来不符合 Android 惯例(Android 团队通常用 “build” 表示递增的构建号)。在这里,请按该字段在 Capgo 中的角色来理解,而不是按名字的字面意思。养成这个小习惯,可以避免发布现场出现很多混乱。

第 2 步:确定原生基线版本和已下载的 bundle

在修改版本值之前,请先分清哪个 code 是原生的,哪个 code 是以 bundle 形式交付的。原生应用就是已安装的 iOS 或 Android 二进制文件。bundle 则包含 Capacitor 应用可通过 OTA 更新接收的 Web 资源。

假设一个原生应用发布时自带基线版本 1.2.3. 后续的 Web 修复会作为 bundle 上传 1.2.4. Capgo 会检查该 channel 的目标 bundle 是否允许用于 native baseline 1.2.3. 如果符合条件,设备就可以下载该 bundle。安装完成后, version_name 反映的是设备上当前的 bundle。native baseline 仍与已安装的 binary 绑定。

当用户使用较旧的 App Store build 但 Web bundle 较新时,这一差异就很关键。bundle 可以在不替换 native binary 的情况下变化,但 OTA 更新无法添加应用里原本没有的 native code。如果某项更改需要新的 plugin 或 native 设置,应规划一次 Native Build,而不是把 bundle 上传当作替代方案。

Capacitor native app baseline 与已下载的 Capgo bundle 示意图。

当数值看起来不同步时,可以用这个快速检查:

  • 确认测试设备上安装的是哪个 native binary。
  • 找到 Capgo 作为 native baseline 收到的 version 值。
  • 检查分配给设备 channel 的 bundle version。
  • 将已安装的 bundle version 与上述两者分开记录。

不要根据以下内容推断 native baseline package.json 除非你的构建流程刻意将该值复制到原生版本或 Capgo 配置中。JavaScript 项目版本和商店安装的 App 版本可能会不一致。正确的来源,是你的 App 实际发送给 Capgo 的那个值。

一旦能确定基准和当前 bundle,下一步就是追溯每个值来自哪个源文件。平台差异往往就出现在这里。

步骤 3:检查原生 App 版本的来源

为了获得可靠结果 version_build,请找到你的 Capacitor App 所报告的原生版本。Capgo 的版本文档分别说明了 iOS 和 Android 的不同来源键,然后将得到的原生值作为 OTA 对比基准。

在 iOS 上

查看 CFBundleShortVersionString 在 App 的 Info.plist。在大多数 Xcode 项目中,这个键会被设为 $(MARKETING_VERSION),因此你实际编辑的值是 target 的 Marketing Version。请在实际构建出的 App 中验证该值,而不只是看模板或可能被构建覆盖的文件。

当团队更新了 Xcode 项目,却没有更新最终进入 App 的值时,本地项目视图可能看起来没问题,但安装后的二进制文件报告的却是另一个值。请把生成的原生 App 中的版本与发布流程期望的值进行对比。

在 Android 上

查看 defaultConfig.versionName 在 Android 应用的 Gradle 配置中。该原生版本名称用于 Capgo 的 OTA 比较。不要将其与 Android 构建 code 或无关的 JavaScript 包版本混淆。对于此检查,关键问题是原生应用发送的版本名称是什么。

共享的版本策略有助于保持两个平台的一致性,但不要假设它们已经共享同一个来源。iOS 和 Android 可能有单独的文件、构建步骤或发布时间。在发布检查期间比较它们的最终值,特别是当一个平台有不同的商店发布计划时。

一些应用明确地在 capacitor.config.ts 中通过更新器配置的 version 值设置原生版本。 Capgo Semver 测试工具 将此原生基线描述为可以来自配置或原生应用元数据的值。如果你的应用覆盖了原生元数据,请记录该选择,以免有人期望商店版本是来源。

针对每个平台,记录源文件、解析后的值以及包含该值的构建版本。发布后,如果仓库中的版本已高于测试设备上的应用版本,这样做能更容易地追踪版本不匹配的问题。

只修改你的构建实际读取的源文件。编辑过时的文件可能会让 code 审查看起来已完成,但打包后的原生版本却未改变。

第 4 步:设置并验证 Capgo 接收到的 bundle 版本

bundle 版本描述的是 JavaScript 更新,而不是已安装的 native binary。Capgo 可以从 version 字段,位于 package.json 当您未提供明确的 bundle 版本时。CLI 的 --bundle 选项可以在 upload 时设置发送的版本。

请选择一条路径,并在发布流程中明确说明。如果 package.json 是来源,请在 upload 前提升该字段的值。如果 CI 通过 CLI 传入 bundle 版本,请让 job 在发布日志中打印解析后的版本。两种路径悄悄混用,会让人更难判断 channel 为什么收到某个特定值。

请使用熟悉的语义化版本 major.minor.patch 形式,例如 1.2.3。Capgo 的 channel 策略会利用该版本号的各部分,判断目标 bundle 是否符合 native 基线。预发布后缀,例如 -beta.1 可以帮助标记特定 channel 的 build,但请确保版本号在你的发布工具中可解析且一致。

发布前先想清楚版本号怎么递增:

  • 同一发布线内的兼容性 Web 修复,使用 patch 变更。
  • 当变更属于新的兼容功能线时,使用 minor 版本变更。
  • 当兼容边界变化、旧版 Native code 可能不支持该 bundle 时,使用 major 版本变更。

这些标签只是团队约定,并不是通过 OTA 增加 Native 能力的方式。版本号无法证明 bundle 对 Native App 安全。实际的兼容性判断应以二进制文件中的 code 和依赖项为依据。

在 upload 前,将 package 版本或 CLI 值与 upload 后 bundle 显示的版本进行对比。还要检查将要分发该 bundle 的 channel。即使 bundle 命名正确,把它 upload 到错误的 channel 仍会导致错误的测试结果。

遇到无效或不一致的字符串,应停下来核对,而不是猜测。保留一个已知可用的 release 值,修正源码,并在发布前测试解析后的版本。

本指南中介绍的 Capgo CLI 命令参考 把 upload 接入脚本时很有用,因为 bundle 版本是 release 命令的输入参数之一。

第 5 步:发布更新前测试 channel 资格

Channel 资格靠对比,而不是猜哪个 bundle 看起来更新。Capgo 会将 channel 的目标 bundle 与以如下形式发送的 Native 基准进行比对: version_build当前下载的 bundle,报告为 version_name,并不是这些 channel 规则的基准。

例如,假设已安装的原生应用报告 1.2.3,而其当前 bundle 为 1.2.4。如果某个 channel 指向 1.2.5,应对照原生基准版本评估目标版本 1.2.3,而不只是对比当前 bundle 1.2.4。允许哪些目标版本取决于该 channel 的更新策略。

Capgo 文档介绍了 major 和 minor 等策略,这些策略会限制相对于原生基准版本的更新。在 major 策略下,主版本号更高的目标版本可能会被拦截。在 minor 策略下,任何改变基准版本主版本或次版本号的目标版本都可能会被拦截。请检查配置的策略,不要假设所有看起来更新的 bundle 都会被接受。

开发者针对原生应用版本测试 OTA bundle 的 Capgo channel 资格。

测试你计划发布的确切组合:

  1. 安装代表目标用户的原生构建。
  2. 确认发送给 Capgo 的原生基准版本。
  3. 将测试设备分配到目标 channel。
  4. 检查 Channel 目标及其版本策略。
  5. 请求更新并确认设备端的结果。

如果用户群同时使用多个商店版本,请在另一个原生基线上运行同样的检查。适用于全新构建的 Bundle 在旧版二进制上可能会被拦截,而这可能正是有意的安全规则。

对于更大范围的发布,请先从测试 Channel 或限量推送开始。在扩大受众前,留意是否有意外的资格判断结果。Capgo 的 Channel 模型让团队可以通过发布 Channel 分发 Bundle;请在发布说明中写清每个 Channel 的目标和预期的原生版本线。

如果测试设备没有更新,请在重新上传前检查它的 Channel 分配和版本值。反复发布同一个 Bundle 并不能解决基线不匹配的问题。

第 6 步:诊断版本不匹配并让发布可重复

当数值与预期不符时,请按顺序排查。先确认设备上的原生 App 版本,再检查配置覆盖是否改变了基线。接着把 Capgo 收到的 Bundle 版本与 Channel 目标对比。按这个顺序,可以区分是源值有误,还是 Channel 规则按设置正常工作。

常见原因包括 bump 版本号 package.json 在保持 Native 版本不变的同时,从不同的 release 分支构建某个平台,并测试分配到另一个 channel 的设备。另一个混淆点是把每个数字都叫成“build 版本”。请记录清楚哪个值是 Native 版本、哪个是上传的 bundle,以及当前安装的是哪个值。

对于 CI/CD,请明确版本输入。让 pipeline 从受控来源读取预期的 release 版本,然后将其传给 upload 命令,或在 upload 步骤前更新 package 字段。在 job 输出中记录解析后的 Native 基准版本和 bundle 目标。避免依赖构建服务器看不到的开发者本地状态。

使用 release gate,在缺少必需版本或格式不符合团队要求时失败。然后在正式发布前,向正确的 channel 跑一次测试 upload。Capgo 支持基于 CLI 的部署流程,因此团队可以把 bundle upload 放进现有的 CI/CD job,并保留可见的命令日志。

不要把这些值与 Android WebView 引擎版本混淆。我们的 @capgo/capacitor-webview-version-checker plugin 会检查设备的 WebView 引擎是否过时,并能显示 Native 更新 prompt。这与 version_build 以及 version_name检查 Native 基准版本和 channel 的目标 bundle 是两回事,因此它永远无法替代这项检查。

从旧方案迁移时,不要一次性重命名所有现有值。先把旧的原生版本映射到原生基线。再把上传的 Web 发布映射到 bundle 版本。在引导用户使用该 channel 策略前,先拿有代表性的现有 App build 进行测试。

保留一份简短的发布记录,包含源码 commit、原生版本、上传的 bundle 版本、channel 和测试结果。如果发布需要暂停或回滚,这份记录能帮团队确认哪个 bundle 去了哪里。它还能让下次部署可重复,而不是靠某人记得改过哪个文件。

常见问题

Capgo 中的 version_build 和 version_name 有什么区别?

version_build 是原生应用的基准版本,而 version_name 是当前已下载的 bundle 版本。Capgo 在检查 channel 的目标 bundle 是否符合条件时,会使用原生基线。在 logs 和发布说明中把这两个值分开记录,这样就能看出安装的是哪个原生 App、它对应哪个 Web bundle。

version_name 会控制是否允许 OTA 更新吗?

不,Capgo 的 channel 版本策略是将目标 bundle 与 version_build,也就是原生基线进行比较。 version_name 用于标识当前已下载的 bundle。如果设备没收到更新,先检查它的基线、channel 目标和已配置的策略,再改当前 bundle 值。

Capgo 从哪里获取原生版本?

在 iOS 上,Capgo 读取 CFBundleShortVersionString,Xcode 通常会自动填充 MARKETING_VERSION。在 Android 上,原生版本来自 defaultConfig.versionName。Capacitor 配置中显式指定的 updater 版本可能会改变应用发送的值,因此请验证构建后的应用。

Capgo 从哪里获取 bundle 版本?

Capgo 可以使用 version 字段,位于 package.json ,当你未传入显式 bundle 版本时。你也可以通过 CLI 的 --bundle 选项提供版本。为你的发布工作流选择一个明确的来源,然后在上传后验证 Capgo 接收到的版本。

总结

使用 version_build 作为原生基线, version_name 作为已安装的 bundle。在下一次发布前,请在测试设备上验证这两个值,并将通道目标与基线进行比较。这一检查可以在版本不匹配影响更广泛用户之前发现它。

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。