如何将语义化版本用于 Capgo OTA 更新

想简化应用更新以及版本控制？ 语义化版本 (SemVer) 结合 Capgo的 Over-The-Air (OTA) 更新让应用管理 Capacitor 变得更简单、更快速。方法如下：

语义化版本 (SemVer) 基础知识： 版本号采用以下格式： MAJOR.MINOR.PATCH:
- MAJOR（主版本号）： 用于破坏性变更。
- MINOR（次版本号）： 用于向后兼容的新功能。
- PATCH（修订号）： 用于修复 Bug。
为什么要在 Capgo 中使用 SemVer？
- 清晰传达更新信息。
- 更智能的版本管理。
- 避免依赖冲突。
- 有序的发布规划。
Capgo 配置步骤：
1. 安装 Capgo 的更新器插件。
2. 在 capacitor.config.json 及其他文件中配置应用版本。
3. 使用您的 API 密钥进行初始化。
4. 使用 Capgo CLI 以打包并上传更新。
管理版本和通道:
- 使用独立通道（例如，“beta”用于测试，“production”用于稳定发布）。
- 控制更新策略（自动更新补丁，重大更改需手动批准）。
- 更新失败时的回滚选项。
部署流程：
- 遵循 SemVer 规则更新版本号。
- 部署前请充分测试。
- 使用 CLI 命令上传并分发更新。

Capgo 确保更新快速、可靠地触达用户，并提供工具以处理中断并维持稳定性。非常适合使用 CI/CD 工作流自动化更新的团队。

小贴士： 始终测试更新，并利用 channels 有效管理分阶段发布。

语义化版本 | Level Up

Capgo 设置指南

Capgo Live Update Dashboard 界面

以下是如何配置 Capgo，以便轻松管理 OTA 更新和版本控制。

初始设置步骤

首先安装 Capgo updater 插件:

npm install @capgo/capacitor-updater  
npx cap sync

请确保您的 capacitor.config.json file 使用语义化版本格式：

{ 
  "appId": "com.example.app", 
  "appName": "My App", 
  "version": "1.0.0" 
}

对于旧项目，请在以下位置更新版本信息：

package.json （查找 version 字段）
android/app/build.gradle （更新 versionName)
ios/App/App.xcodeproj/project.pbxproj （更新 CURRENT_PROJECT_VERSION)

配置完成后，使用您的 API 密钥初始化 Capgo：

npx @capgo/cli@latest init YOUR_API_KEY

快速参考表：

配置阶段	关键操作	验证步骤
安装	安装插件并同步	查看 `package.json`
配置	设置版本号	验证所有文件
初始化	使用 API 密钥连接	测试连接状态
构建	创建初始 bundle	确认上传成功

版本控制集成

Capgo 与 CI/CD 平台配合良好，使自动更新变得简单。支持的平台包括：

如果你正在进行本地开发，可以在配置中添加以下内容来禁用自动更新：

{ 
  "plugins": { 
    "CapacitorUpdater": { 
      "autoUpdate": false 
    } 
  } 
}

这样可以确保 Capgo 不会覆盖你的本地更改。配置完成后，上传你的第一个版本：

npx @capgo/cli@latest bundle upload  
npx @capgo/cli@latest channel set production -s default

最后，在应用的主文件中通知原生插件 bundle 的健康状态：

import { CapacitorUpdater } from '@capgo/capacitor-updater';  
CapacitorUpdater.notifyAppReady();

此配置可确保你的应用能够顺利进行 OTA 部署和版本管理。

在 Capgo 中使用语义化版本控制

版本号管理

Capgo 使用语义化版本控制 (SemVer) 管理应用版本，格式为 主版本号.次版本号.修订号。其工作原理如下：

主版本号 (X.0.0)：当变更破坏兼容性时，递增 MAJOR 版本号。
次版本号 (1.X.0)：新增保持兼容的功能时，递增 MINOR 版本号。
修订版本号 (1.0.X)：修复不影响兼容性的 bug 时，递增 PATCH 版本号。

版本类型	何时递增	自动更新行为
主版本 (X.0.0)	用于破坏性 API 变更	需要手动审批
次版本 (1.X.0)	用于新功能	可在 Capgo 中配置
补丁版本 (1.0.X)	用于修复 Bug	通常自动执行

遵循 SemVer 规则可以简化版本管理，并确保跨部署渠道的更新更加顺畅。

版本控制指南

Capgo 允许你为工作流的不同阶段设置独立渠道，从而有效管理部署。

基于渠道的版本管理：通过为测试和生产环境创建独立渠道来组织部署流程。例如：
- 使用 “beta” 渠道（例如 1.2.0-beta）来测试新功能。
- 保留 “production” 渠道（例如 1.2.0）用于稳定版本发布。
- 在处理平台特定问题时，添加平台专属渠道（例如版本为 1.2.1 的 “ios-hotfix”）。
更新策略配置：使用 Capgo 的配置选项控制更新应用方式。例如：
```
{
  "plugins": {
    "CapacitorUpdater": {
      "disableAutoUpdate": "minor"
    }
  }
}
```
此配置确保用户自动接收补丁更新，而次要版本和主要版本更新需要手动批准。
版本回滚策略：使用预发布标识符以保持清晰的回滚选项。这种方法允许你在出现问题时回退到之前的版本，同时保持所有渠道的版本一致性。

这些最佳实践使管理更新、测试新功能以及维护应用部署过程的稳定性变得更加容易。

sbb-itb-f9944d2

OTA 更新部署

版本管理设置就绪后，请按照以下步骤有效部署 OTA 更新。

更新准备

首先，更新 package.json 以及 capacitor.config.json。确保版本符合 SemVer 格式（MAJOR.MINOR.PATCH）：

Bug 修复：递增 PATCH 号（例如 1.0.1 → 1.0.2）
新功能：递增 MINOR 号（例如 1.0.0 → 1.1.0）
破坏性变更：递增 MAJOR 号（例如 1.0.0 → 2.0.0）

彻底测试你的 build，并确认应用通过以下方式使用服务器通信： notifyAppReady.

接下来，确定你的更新策略。您可以选择：

自动更新：自动强制最低版本要求。
手动控制：为更新指定确切的版本要求。
基于渠道：使用渠道进行测试和分阶段发布。

Capgo CLI 更新命令

使用 Capgo 的 CLI 轻松部署您的更新。方法如下：

# Initialize Capgo in your project
npx @capgo/cli@latest init [apikey]

# Upload your update bundle
npx @capgo/cli bundle upload [appId]

# Add a new distribution channel
npx @capgo/cli channel add [channelName] [appId]

Capgo 通过端到端加密和安全的密钥管理确保部署安全。

“@Capgo 是做热 code 推送的明智方式（不用像 @AppFlow 那样花天价）🙂”

部署完成后，您可以通过 Capgo 的 dashboard 监控更新。用户打开应用后，更新通常会在几分钟内送达。流程如下：

应用检查更新。
在后台下载更新。
用户退出应用时，将新版本标记为激活状态。
下次启动时应用更新。

对于企业级部署，您可能希望集成 CI/CD 自动化。

“我们践行敏捷开发，@Capgo 对持续向用户交付至关重要！”

问题解决与技巧

版本管理问题

在 Capgo 中管理语义化版本有时会使更新部署变得复杂。为避免覆盖开发工作，请在您的中配置以下内容 capacitor.config.json 文件：

{ 
  "plugins": { 
    "CapacitorUpdater": { 
      "autoUpdate": false 
    } 
  } 
}

如果更新失败，您可以执行以下操作：

设置 autoUpdate 改为 false 在开发期间。
卸载应用。
用修正后的版本重新安装。
待一切稳定后，重新启用自动更新。

对于主版本更新，请使用 disableAutoUpdateBreaking 标志并监听 majorAvailable 用于正确处理更新的事件：

CapacitorUpdater.addListener('majorAvailable', (info) => {
  console.log(`Major update available: ${info.version}`);
  // Add your update prompt logic here
});

结合这些配置和良好的团队实践，你可以保持版本一致性并减少错误。

团队版本控制

单个更新管理好后，团队建立严格的版本控制实践至关重要。

“在合并到主仓库前测试每项更改，能增强稳定性并避免代价高昂的错误” [4]

以下是确保一致性的几种方法：

将一个分支定义为 主仓库 作为唯一可信来源。
为开发和生产环境分别使用独立的 Capgo channel。
通过 CI/CD pipeline 自动上传版本。
用清晰详细的 commit message 记录所有 code 变更。

对于较大的团队，以下版本管理矩阵有助于组织更新：

环境	渠道	自动更新	版本模式
开发	dev	已禁用	0.x.x
Staging 环境	测试版	已启用	x.x.x-beta
生产环境	stable	已启用	x.x.x

更新恢复步骤

即使采取了预防措施，更新仍可能失败。如果发生这种情况，请遵循以下恢复步骤：

回滚到之前的稳定 bundle。
为任何新修复递增版本号（注意：删除后版本号不能重复使用） [2].
在应用启动时验证更新，确保其按预期工作。

Capgo 的更新器旨在处理中断。例如，如果服务器无法访问或更新被删除，应用将继续正常运行 [3]。此外，失败的网络请求会在下次应用启动时自动重试 [3]。这种内置的弹性最大限度地减少了停机时间，确保了更平稳的运行。

总结

语义化版本控制结合 Capgo，使 Capacitor 应用的 OTA 更新更加高效。已交付 9.476 亿次更新，1,400 个生产应用正在使用此系统 [1]，部署流程效率提升了 81% [1]。这种设置允许开发者快速且受控地推送更新，绕过应用商店的延迟。

听听开发者怎么说：

“我们推出了 Capgo OTA 更新在 5000+ 用户的生产环境中使用，运行非常顺畅，几乎所有用户在 OTA 部署到 @Capgo 后几分钟内就更新到最新版本。” —— colenso [1]

MAJOR.MINOR.PATCH 版本系统让沟通破坏性变更、新功能和 bug 修复变得轻而易举 [5]。对于每周通过 Capgo 平台管理多个发布的团队来说，这一点尤其有帮助。

Capgo 的加密解决方案，与 CI/CD 工具集成后也更具成本优势——五年内最多可节省 26,100 美元 [1]。其可自定义的 Channel 能确保更新在合适的时间触达合适的用户。

“我们采用敏捷开发，@Capgo 对于向用户持续交付至关重要！” —— Rodrigo Mantica [1]

继续阅读：如何在 Capgo OTA Updates 中使用语义化版本

如果你正在使用 如何将语义化版本用于 Capgo OTA 更新 要规划回滚和版本控制，请将其与回滚有关 Rollbacks 的实现细节，版本定向有关 Version Targeting 的实现细节，更新行为有关 Update Behavior 的实现细节， bundle 有关 bundle 的实现细节，以及 Capgo Live Update 有关 Capgo Live Updates 的产品工作流。