如何在 Capgo OTA 更新中使用语义化版本控制

想要简化更新应用更新与版本控制吗？ 语义化版本 (SemVer) 结合 Capgo的 Over-The-Air (OTA) 更新让应用管理 Capacitor 变得更简单、更高效。具体操作如下：

语义化版本 (SemVer) 基础知识： 版本号采用以下格式： MAJOR.MINOR.PATCH:
- MAJOR (主版本号)： 用于包含不兼容的重大变更。
- MINOR (次版本号)： 用于向下兼容的新功能。
- PATCH (修订号)： 用于修复 Bug。
为什么要在 Capgo 中使用 SemVer？
- 清晰的更新沟通。
- 更智能的版本管理。
- 避免依赖冲突。
- 有序的发布规划。
Capgo 配置步骤：
1. 安装 Capgo 的 updater plugin。
2. 在以下文件中配置应用的 version： capacitor.config.json 以及其他文件。
3. 使用您的 API key 进行初始化。
4. 使用 Capgo CLI 进行 bundle 打包并 upload 更新。
管理版本与 Channel:
- 使用独立的 Channel（例如：使用 “beta” 进行测试，使用 “production” 进行稳定版发布）。
- 控制更新策略（自动更新 patch，重大变更需手动审批）。
- 针对更新失败提供 Rollback 选项。
部署流程：
- 遵循 SemVer 规则更新版本号。
- 部署前进行彻底测试。
- 使用 CLI 命令来 upload 并分发更新。

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

小贴士： 务必测试更新，并利用 Channel 有效管理分阶段发布。

语义化版本控制 | 进阶指南

Capgo 配置指南

Capgo Live Update Dashboard 界面

本文将教你如何配置 Capgo，从而轻松管理 OTA 更新与版本控制。

初始配置步骤

首先安装 Capgo updater 插件:

npm install @capgo/capacitor-updater  
npx cap sync

请确保你的 capacitor.config.json 文件使用语义化版本格式：

{ 
  "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 中使用语义化版本控制 (Semantic Versioning)

版本号管理

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 允许你通过为工作流的不同阶段设置不同的 Channel，从而实现高效的部署管理。

基于 Channel 的版本管理: 通过为测试和生产环境创建独立的 Channel 来优化部署流程。例如：
- 使用 “beta” Channel（如 1.2.0-beta）来测试新功能。
- 保留 “production” Channel（如 1.2.0）用于稳定版本发布。
- 在处理特定平台问题时，添加平台特定的 Channel（如版本为 1.2.1 的 “ios-hotfix”）。
更新策略配置: 使用 Capgo 的配置选项来控制更新的生效方式。例如：
```
{
  "plugins": {
    "CapacitorUpdater": {
      "disableAutoUpdate": "minor"
    }
  }
}
```
此设置可确保用户自动获取 patch 更新，而 minor 和 major 更新则需要手动确认。
版本回滚策略: 利用 pre-release 标识符来保持清晰的回滚选项。这种方法允许你在出现问题时回滚到之前的版本，同时保持所有 Channel 的版本一致性。

这些最佳实践能让你更轻松地管理更新、测试新功能，并确保 App 部署过程的稳定性。

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)
破坏性变更 (Breaking Change)：增加 MAJOR 版本号 (例如 1.0.0 → 2.0.0)

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

接下来，确定你的更新策略。你可以从以下方案中选择：

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

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 监控更新情况。通常在用户打开 App 后几分钟内，更新即可送达。其工作流程如下：

App 检查更新。
在后台下载更新。
当用户退出 App 时，将新版本标记为 active。
在下次启动时应用更新。

对于企业级部署，您可能需要集成 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]

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

将一个分支定义为 主仓库 作为事实来源 (source of truth)。
为开发和生产环境使用独立的 Capgo channel。
通过 CI/CD pipeline 实现版本自动 upload。
使用清晰详细的 commit message 记录所有 code 更改。

对于规模较大的团队，可以使用以下版本管理矩阵来规范更新流程：

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

更新恢复步骤

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

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

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

总结

语义化版本控制（Semantic Versioning）结合 Capgo，使 Capacitor 应用的 OTA 更新变得更加高效。目前已有 9.476 亿次更新交付，1,400 个生产环境应用正在使用该系统 [1]，部署流程的效率提升了 81% [1]。这种配置允许开发者快速且受控地推送更新，从而绕过 App Store 的延迟。

以下是开发者的评价：

“我们为超过 5000 名用户推出了 Capgo OTA 更新。我们观察到运行非常顺畅，几乎所有用户在 OTA 部署到 @Capgo 后几分钟内就能完成更新。” —— colenso [1]

MAJOR.MINOR.PATCH 版本控制系统让沟通破坏性变更（breaking changes）、新功能和 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 Updates 用于 Capgo Live Updates 中的产品工作流。