Capgo Semver 测试工具

根据以 version_build 发送的原生基准版本，检查 Channel 策略的兼容性

原生基准版本

作为 version_build 发送到 Capgo 的原生版本，来自配置或原生应用元数据。

远程版本

分配给已解析 Channel 的 bundle 版本。

输入两个语义化版本进行对比

“Native Baseline Version” 的含义

Native Baseline Version 是设备向 Capgo 请求 bundle 时， version_build 作为原生应用版本发送的值。在 Capacitor 应用中，该值可来自 CapacitorUpdater.version 中的 capacitor.config.*。如果未设置该项，插件将回退使用 iOS 或 Android 的原生应用版本。请勿直接将其视为你的 package.json 版本，除非你的 build 过程已将该值复制到 config 或原生元数据中。

Capgo 仍使用 version_name 来确定当前安装的是哪个已下载的 bundle。Channel 的 semver 策略（例如 major, minor，以及 patch 会将远程 bundle 与以下版本进行对比 version_build.

Capacitor 配置

设置 CapacitorUpdater.version 当你希望 App 发送一个明确的版本号时。

优点： 在 iOS 和 Android 构建中保持一致非常简单。

缺点： 如果在 Native Build 发布前忘记更新，过时的配置可能会报告错误的版本号。

原生 App 版本

使用平台版本，例如 iOS CFBundleShortVersionString 或 Android versionName.

优点： 与用户从 TestFlight、App Store、Play Store 或内部测试安装的二进制文件相匹配。

缺点： 更改此项需要进行 Native Build；如果发布设置发生偏移，不同平台的结果可能会有所不同。

Bundle 目标版本

将其与远程 Bundle 版本、Channel SemVer 规则或元数据上传限制进行对比，例如： --min-update-version。该 Channel 必须使用 --disable-auto-update metadata.

Pro 版： 防止向旧版 App 二进制文件发送需要更新 Native code 的 JavaScript 代码。

缺点： 规则过于严格可能会阻塞有效的更新，直到调整 Channel 或 Bundle 元数据为止。

在此测试器中，请输入设备发送的 Native 基准版本作为 version_build，然后将其与您希望 Capgo 推送的远程 Bundle 版本进行对比。

为什么 Capgo 使用语义化版本控制 (SemVer)

语义化版本规范是软件开发中最广泛采用的版本管理标准。通过使用 semver，Capgo 能确保在向您的 Capacitor 应用推送 Live Update 时，兼顾兼容性与安全性。

semver 标准让 Capgo 能够精准识别每次更新包含的具体变更：

补丁更新 (Patch, 1.0.0 → 1.0.1)： Bug 修复，可安全地自动应用
次要更新 (Minor, 1.0.0 → 1.1.0)： 新增功能，向下兼容
重大更新 (Major, 1.0.0 → 2.0.0)： 破坏性变更，需要通过原生应用商店发布

这可以防止 Capgo 向您的原生 code 发送不兼容的更新，从而避免用户遇到崩溃，确保您的应用保持稳定。

灵活的 Semver 策略：超越基础版本管理

虽然 semver 对核心格式有严格要求，但您仍可以通过以下方式根据团队需求进行扩展： pre-release 标识符 以及 构建元数据:

🏷️ 构建元数据 (+) - “装饰性”层

1.2.0+20240315.142530

用于部署追踪的时间戳

1.2.0+ui.refresh.dark-mode

面向设计团队的 UI 更新说明

1.2.0+build.4729.commit.a1b2c3d

CI/CD 构建号与 git commit

重要提示： 构建元数据不参与版本优先级比较 - 1.2.0+anything 等于 1.2.0 对 Capgo 的更新逻辑而言。

🔧 预发布标识符 (-) - 开发渠道

1.3.0-beta.1

Beta 测试渠道

1.3.0-hotfix.payment

紧急修复分支

1.3.0-feature.newapi

功能分支测试

注意： 预发布版本优先级较低 - 1.3.0-beta.1 < 1.3.0

🎯 混合方案 - 两全其美

1.3.0-rc.1+ui.redesign.20240315

带 UI 元数据和时间戳的候选发布版本

Semver 实际应用场景与团队策略

🚀 初创公司 / 快速迭代

0.1.0 - 首个 MVP 版本

0.2.0-beta.1 - 新功能测试

0.2.0+ui.v2 - UI 改版元数据

1.0.0 - 生产环境就绪

1.0 前使用 0.x.x，用元数据追踪设计

🏢 企业级 / 受监管行业

2.1.0 → 季度版本发布

2.1.1+sec.patch.cve2024 → 带追踪记录的安全补丁

2.2.0-rc.1+audit.ready → 审计前的候选版本

严格 Semver，带合规元数据

🎮 游戏 / 创意类应用

1.0.0+season.winter.2024 → 季节性内容

1.1.0+event.halloween → 事件驱动型功能

1.2.0+assets.hd.remaster → 资源更新

用于内容追踪的创意元数据

⚡ 热修复策略

1.2.0 → 当前生产环境

1.2.1-hotfix.payment → 紧急 Bug 修复

1.2.1+urgent.20240315.1430 → 带有时间戳的发布版本

用于测试的预发布版本，包含部署追踪元数据

🌍 多平台策略

1.3.0+ios.optimized → iOS 特定优化

1.3.0+android.material3 → Android 设计更新

1.3.0+web.pwa.ready → PWA 功能

版本相同，但包含平台特定元数据

🔄 CI/CD 集成

1.4.0-alpha.1+build.123 → 自动化预发布

1.4.0+deploy.staging.456 → Staging 环境部署

1.4.0+prod.final.789 → Production 环境部署

结合部署元数据的自动化版本管理

💡 专业技巧：

使用 build 元数据 (+) 进行追踪、记录时间戳或不影响兼容性的修饰信息
使用 pre-release 标识符 (-) 为需要不同更新优先级的开发渠道设置版本
结合两者以获得最大的灵活性： 1.2.0-beta.1+ui.dark.theme.20240315
请记住：Capgo 遵循 semver 优先级规则，因此请据此规划你的 channel 策略

重要：Capgo 使用严格的语义化版本控制

与 npm 的 semver 实现不同，Capgo 严格遵循官方 SemVer 规范。npm 的 node-semver 与规范存在已知偏差，可能导致意外行为。

例如，npm 对以下版本的处理方式 1.0.0-alpha.1 与规范要求不符。请参阅我们的已报告的问题以及尝试过的修复但从未被合并。

有效的语义化版本

1.0.0 ✓ 标准版本

2.1.3-alpha ✓ 预发布版本

1.0.0-beta.1 ✓ 带编号的预发布版本

1.0.0+build.1 ✓ 构建元数据

1.0.0-rc.1+build.1 ✓ 完整版本号

无效的语义化版本

v1.0.0 ✗ 不允许以 'v' 开头

1.0 ✗ 缺少 patch 版本号

1.0.0.0 ✗ 版本号段过多

1.0.0- ✗ 预发布版本为空

1.0.0+ ✗ 构建元数据为空

Capgo 更新行为

✓ Minor 策略允许同一 major.minor 版本线内的 patch 变更，例如 1.0.0 -> 1.0.1

✓ Patch 策略会阻止 1.0.0 -> 1.0.1，只允许类似 1.0.0-beta.1 -> 1.0.0-beta.2 的后缀变更。

✗ Major 策略会拦截主版本号高于 Native Build 基准的版本，例如 1.0.0 -> 2.0.0

⚠ 降级保护遵循完整的 semver 优先级，因此稳定的 1.0.0 比 1.0.0-beta.2 更晚发布

本工具遵循官方的 Semantic Versioning 规范与 npm 的实现方式不同。