跳转到正文

版本定向

本指南介绍如何根据用户的原生应用版本,自动向用户下发最新的兼容 bundle, 与 Ionic AppFlow 的做法类似。这样既能简化更新管理、加快发布速度,又能避免兼容性问题。

Capgo 的版本定向系统让你可以:

  • 自动分发兼容更新 给原生应用版本匹配的用户
  • 防止破坏性变更 波及不兼容的应用版本
  • 同时管理多个应用版本 无需复杂逻辑
  • 无缝发布更新 到特定用户群

为什么版本定向很重要(尤其是 AppFlow 用户)

章节标题:“为什么版本定向很重要(尤其是 AppFlow 用户)”

如果你熟悉 Ionic AppFlow,你就会明白,确保用户只收到兼容更新有多重要。AppFlow 会自动将 live update bundle 与原生应用版本匹配,避免不兼容的 JavaScript 被下发到旧版原生 code。

Capgo 提供相同的安全保障,还提供以下额外功能:

  • 更细粒度的版本匹配控制
  • 多种策略(频道、semver、原生约束)
  • 更清晰地了解版本分布
  • API 和 CLI 与 Dashboard 管理协同工作

这种方法在以下场景中特别有用:

  • 您的用户处于应用的不同主要版本(例如 v1.x、v2.x、v3.x)
  • 您需要保持向后兼容性的同时,推出破坏性变更
  • 您希望防止较新的 bundle 破坏较旧的 code 原生代码
  • 您正在逐步将用户从一个版本迁移到另一个版本
  • 您正在从 AppFlow 迁移 并希望保持相同的更新安全性

Capgo 采用多层策略,将用户与兼容的更新进行匹配:

  1. 原生版本约束: 防止 bundle 被下发到不兼容的原生版本
  2. 基于 Channel 的路由: 将不同 App 版本路由到不同更新 Channel
  3. 语义化版本控制: 自动拦截跨 major/minor/patch 边界的更新
  4. 设备级覆盖: 针对特定设备或用户群
graph TD
A[User Opens App] --> B{Check Device Override}
B -->|Override Set| C[Use Override Channel]
B -->|No Override| D{Check local plugin channel}
D -->|setChannel value| E[Use local setChannel channel]
D -->|No local channel| F{Check defaultChannel in App}
F -->|Has defaultChannel| G[Use App's defaultChannel]
F -->|No defaultChannel| H[Use Cloud Default Channel]
C --> I{Check Version Constraints}
E --> I
G --> I
H --> I
I -->|Compatible| J[Deliver Update]
I -->|Incompatible| K[Skip Update]

这是 推荐的方法 用于管理破坏性变更和主要版本更新。它类似于 AppFlow 的交付模型。

  • App v1.x (100,000 用户)→ production 渠道
  • App v2.x (50,000 用户,包含破坏性变更)→ v2 渠道
  • App v3.x (10,000 名 Beta 用户)→ v3 渠道
// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production', // or omit for default
}
}
};
export default config;
// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // Routes v2 users automatically
}
}
};
// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example App',
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v3', // Routes v3 users automatically
}
}
};
终端窗口
# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add v3
# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

步骤 3:上传特定版本的 Bundle

标题为“步骤 3:上传特定版本的 Bundle”
终端窗口
# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production
# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2
# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3
  • 零 code 修改 - Channel 路由自动完成
  • 清晰分离 - 每个版本都有独立的更新 pipeline
  • 灵活定向 - 向指定版本组推送更新
  • 安全发布 - Breaking changes 绝不会影响不兼容的版本

使用 Capgo 内置的 语义化版本控制功能 来防止更新跨越版本边界。

终端窗口
# Create a channel that blocks major version updates
npx @capgo/cli channel add stable
npx @capgo/cli channel set stable --disable-auto-update major

此配置意味着:

  • App 版本为 1.2.3 的用户将收到最高至 1.9.9
  • 用户将 不会 收到版本 2.0.0 自动
  • 防止破坏性变更影响旧版 Native code
  • 该比较使用作为 version_build
终端窗口
# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor
# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch
# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

为每个 bundle 指定最低 native 应用版本 (min_update_version),以便 Capgo 只将其下发给 native 二进制足够新的设备。

这使用了 channel 元数据 策略 (--disable-auto-update metadata) 以及 --min-update-version 或 --auto-min-update-version 上传时。没有 --native-version CLI 标志。

终端窗口
# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

上传 bundle 时,请指定允许接收该 bundle 的最低原生版本:

终端窗口
# This bundle requires native version 2.0.0 or higher
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "2.0.0"

或者让 Capgo 根据原生包兼容性自动设置下限:

终端窗口
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version
  1. 需要新的原生插件

    终端窗口
    # Bundle needs Camera plugin added in v2.0.0
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "2.0.0"
  2. Native API 的破坏性变更

    终端窗口
    # Bundle uses new Capacitor 6 APIs
    npx @capgo/cli@latest bundle upload \
    --channel production \
    --min-update-version "3.0.0"
  3. 渐进式迁移

    终端窗口
    # one-time: enable metadata gating on beta
    npx @capgo/cli@latest channel set beta --disable-auto-update metadata
    # Test bundle only on latest native version
    npx @capgo/cli@latest bundle upload \
    --channel beta \
    --min-update-version "2.5.0"

防止用户收到比当前原生版本更旧的 bundle。

在 Capgo dashboard 中:

  1. 前往 通道 → 选择你的 channel
  2. 启用 “在 native 下禁用自动降级”
  3. 保存更改

或者通过 CLI:

终端窗口
npx @capgo/cli@latest channel set production --no-downgrade
  • 用户设备:Native 版本 1.2.5
  • Channel bundle:版本 1.2.3
  • 结果:更新被阻止(将会导致版本降级)

适用于以下场景:

  • 用户已从应用商店手动安装了更新版本
  • 您需要确保用户始终拥有最新的安全补丁
  • 您希望防止回归 bug

为特定设备或用户组覆盖 channel 分配。

import { CapacitorUpdater } from '@capgo/capacitor-updater'
// Force beta testers to use v3 channel
async function assignBetaTesters() {
const deviceId = await CapacitorUpdater.getDeviceId()
// Check if user is beta tester
if (isBetaTester(userId)) {
await CapacitorUpdater.setChannel({ channel: 'v3' })
}
}

在 Capgo dashboard 中:

  1. 前往 设备 → 查找设备
  2. 点击 设置 Channel 或 设置 Version
  3. 用指定 channel 或 bundle version 覆盖
  4. 设备将从覆盖后的来源接收更新

以下是结合所有策略的完整示例:

终端窗口
# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
--disable-auto-update metadata \
--no-downgrade
capacitor.config.ts
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'production',
}
}
};

2. 发布破坏性变更 (App v2.0.0)

章节“2. 发布破坏性变更 (App v2.0.0)”
终端窗口
# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
--disable-auto-update metadata \
--no-downgrade \
--self-assign
# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance
// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
plugins: {
CapacitorUpdater: {
autoUpdate: 'atBackground',
defaultChannel: 'v2', // New users get v2 channel
}
}
};

3. 向两个版本推送更新

章节“3. 向两个版本推送更新”
终端窗口
# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli@latest bundle upload \
--channel production \
--min-update-version "1.0.0"
# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli@latest bundle upload \
--channel v2 \
--min-update-version "2.0.0"

使用 Capgo dashboard 跟踪:

  • v1 与 v2 的用户数量对比
  • 各版本的 Bundle 采用率
  • 各版本的错误或崩溃情况

当 v1 的使用率降至阈值以下时:

终端窗口
# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance
# Move all remaining users to default
# (They'll need to update via app store)

当存在多个 channel 配置时,Capgo 使用以下优先级顺序:

  1. 设备覆盖 (Dashboard 或 API) - 优先级最高,且在 Device Override UI 中可见
  2. 本地插件频道 通过 setChannel() - 仅存储在设备上,不会在 Device Override UI 中显示
  3. defaultChannel 在 capacitor.config.ts 中
  4. 默认频道 (云端设置) - 优先级最低
// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3
// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually
终端窗口
# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
# ❌ Bad
1.0 → 1.1 → 2 → 2.5
终端窗口
# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions
终端窗口
# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel first
npx @capgo/cli@latest bundle upload \
--channel beta \
--auto-min-update-version
# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
--channel production \
--auto-min-update-version

定期检查您的 dashboard:

  • 用户是否正在升级到新的 Native 版本?
  • 旧版本是否仍有高流量?
  • 是否应该弃用旧的 Channel?

对于正在从以下平台迁移的团队: Ionic AppFlow,以下是 Capgo 版本定向功能的对比:

功能Ionic AppFlowCapgo
基于版本的路由基于原生版本自动匹配通过以下方式自动执行 defaultChannel + 多种策略
语义化版本控制基础支持高级功能,支持 --disable-auto-update (主版本/次版本/修订号)
原生版本约束在 Appflow 仪表板中手动配置内置 --min-update-version / --auto-min-update-version 带元数据通道
频道管理Web UI + CLIWeb UI + CLI + API
设备覆盖设备级控制有限通过 Dashboard/API 实现完全控制
防止自动降级是是,通过 --no-downgrade
多版本维护手动管理分支/Channel基于 Channel 优先级自动管理
自托管否是(完全控制)
版本分析基础版详细的按版本指标

请检查以下各项:

  1. Channel 分配:确认设备在正确的 channel 上

    const channel = await CapacitorUpdater.getChannel()
    console.log('Current channel:', channel)
  2. 版本约束:检查 bundle 是否有原生版本要求

    • Dashboard → Bundles → 检查“Native Version”列
  3. Semver 设置:确认 channel 的 disable-auto-update 设置

    终端窗口
    npx @capgo/cli channel list
  4. 设备覆盖:检查设备是否启用了手动覆盖

    • Dashboard → Devices → 搜索设备 → 检查 channel/version
  1. 检查 defaultChannel:确保 中的 channel 正确 capacitor.config.ts
  2. 检查 Bundle 上传:验证 bundle 已上传到目标 channel
  3. 检查最低更新版本: 确认 --min-update-version (或 --auto-min-update-version) 已设置,且该 channel 使用 --disable-auto-update metadata
  1. 立即修复方案: 将受影响的设备覆盖到安全 bundle
    • Dashboard → 设备 → 批量选择 → 设置版本
  2. 长期修复方案: 创建版本化 channel 并维护独立分支
  3. 预防措施: 在发布更新前,务必在代表性设备上进行测试

从 Ionic AppFlow 迁移

“从 Ionic AppFlow 迁移”部分

如果您正在从 Ionic AppFlow迁移,Capgo 中的版本目标设置非常相似,且灵活性更高:

AppFlow 概念Capgo 对应项备注
部署通道Capgo 通道概念相同,功能更强
原生版本锁定--min-update-version / --auto-min-update-version更细粒度的控制
通道优先级通道优先级(覆盖 → 云端 → 默认)优先级更透明
部署目标通道 + semver 控制提供多种策略
生产环境频道production channel(或任意名称)灵活命名
基于 Git 的部署从分支执行 CLI bundle upload相同的工作流
自动版本匹配defaultChannel + 版本约束增强多种策略
  1. 更多控制:Capgo 提供多种可组合的策略(channels、semver、native version)
  2. 更好的可见性:Dashboard 显示版本分布和兼容性问题
  3. API 访问权限:对版本目标进行完全的程序化控制
  4. 自托管:选择运行自己的更新服务器,使用相同的版本逻辑
  1. 映射您的 Appflow 频道 到 Capgo 频道(通常 1:1)
  2. 设置 defaultChannel 中的 capacitor.config.ts 针对每个主版本
  3. 配置 semver 规则 如果您希望在版本边界处自动拦截
  4. 上传特定版本的 bundle 使用 --min-update-version (channel 必须使用 metadata 策略)
  5. 监控版本分布 在 Capgo dashboard 中
// Gradually migrate v1 users to v2
async function migrateUsers() {
const deviceId = await CapacitorUpdater.getDeviceId()
const rolloutPercentage = 10 // Start with 10%
// Hash device ID to get deterministic percentage
const hash = hashCode(deviceId) % 100
if (hash < rolloutPercentage) {
// User is in rollout group - migrate to v2
await CapacitorUpdater.setChannel({ channel: 'v2' })
}
}
// Enable features based on native version
async function checkFeatureAvailability() {
const info = await CapacitorUpdater.getDeviceId()
const nativeVersion = info.nativeVersion
if (compareVersions(nativeVersion, '2.0.0') >= 0) {
// Enable features requiring v2.0.0+
enableNewCameraFeature()
}
}
// Run A/B tests within same native version
async function assignABTest() {
const nativeVersion = await getNativeVersion()
if (nativeVersion.startsWith('2.')) {
// Only A/B test on v2 users
const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
await CapacitorUpdater.setChannel({ channel: variant })
}
}

Capgo 针对特定版本的更新分发提供多种策略:

  1. 基于 Channel 的路由:通过自动版本隔离 defaultChannel
  2. 语义化版本规范:防止跨主版本/次版本/补丁版本边界的更新
  3. 原生版本约束:要求 bundle 满足最低原生版本
  4. 自动降级防护:绝不向较新的原生版本下发较旧的 bundle
  5. 设备级覆盖:用于测试和定向的手动控制

结合这些策略,你可以实现类似 AppFlow 的自动更新分发,同时拥有更高的灵活性和控制力。选择最适合你应用版本管理和部署工作流的方式。

有关具体功能的详细信息:

如果你正在使用 版本定向 要规划 Channel 路由和分阶段发布,请将其与 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, Beta 测试解决方案 适用于 Beta Testing Solution 产品工作流的,以及 版本定向解决方案 适用于 Version Targeting Solution 产品工作流的。