版本定向

本指南将介绍如何根据用户的 Native Build 版本，自动向其推送最新的兼容 Bundle， 其逻辑类似于 Ionic AppFlow 的方式。这能在防止兼容性问题的同时，简化更新管理并加快发布速度。

正在从 Ionic AppFlow 迁移？

如果你之前使用 Ionic AppFlow，本指南对你尤为重要。AppFlow 会自动将更新与 Native Build 版本进行匹配，而 Capgo 同样提供此功能，并具备更高的控制力和灵活性。请参阅 AppFlow 迁移指南 以获取逐步迁移说明。

概览

Capgo 的版本定向系统允许你：

• 根据用户的 Native Build 版本 自动推送兼容的更新
• 防止破坏性变更 影响不兼容的应用版本
• 无需复杂逻辑即可 同时管理多个应用版本
• 无缝发布更新 至特定的用户群体

为什么版本定向至关重要（尤其是 AppFlow 用户）

如果你熟悉 Ionic AppFlow，你就会知道确保用户仅接收兼容更新有多么关键。AppFlow 会自动将 live update bundle 与原生应用版本进行匹配，从而防止将不兼容的 JavaScript 推送给旧版原生 code。

Capgo 提供同样的安全性保障，并具备以下额外功能：

• 更精细的版本匹配控制
• 多种策略（channels、semver、原生约束）
• 更清晰的版本分发视图
• API 与 CLI 可配合 dashboard 管理进行控制

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

• 用户分布在应用的不同主版本中（例如 v1.x, v2.x, v3.x）
• 在发布重大变更（breaking changes）的同时需要保持向后兼容性
• 防止较新的 bundle 破坏旧版的 Native code
• 正在将用户从一个版本逐步迁移到另一个版本
• 正在从 AppFlow 迁移 并希望保持相同的更新安全性

工作原理

Capgo 使用多层匹配机制，确保用户获得兼容的更新：

1. Native 版本约束: 防止 bundle 被推送到不兼容的 Native Build 版本
2. 基于 Channel 的路由: 将不同的 App 版本路由到不同的更新 Channel
3. 语义化版本控制 (SemVer): 自动拦截跨 Major/Minor/Patch 边界的更新
4. 设备级覆盖 (Overrides): 针对特定设备或用户群进行推送

版本匹配流程

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]

策略 1：基于 Channel 的版本路由

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

示例场景

• App v1.x (100,000 用户) → production channel
• App v2.x (50,000 用户，包含破坏性变更) → v2 channel
• App v3.x (10,000 名 beta 用户) → v3 channel

实现

步骤 1：为每个主版本配置 Channel

// 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
    }
  }
};

步骤 2：创建 Channel

# 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

# 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

自动路由

当用户打开 App 时，他们会根据其已安装 App Bundle 中的 defaultChannel 自动连接到指定的 Channel。无需修改任何 JavaScript code！

优势

• 零 code 修改 - 自动进行 Channel 路由
• 清晰的分离 - 每个版本都有独立的更新 pipeline
• 灵活的版本定位 - 向特定的版本组推送更新
• 安全的发布流程 - Breaking changes 绝不会影响不兼容的版本

策略 2：语义化版本控制

利用 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
• 比较时会使用发送的 Native baseline 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

必须使用语义化版本控制

此策略仅在您遵循以下规则时有效 语义化版本控制 (semver) 用于您的应用版本。请确保您的版本号符合 MAJOR.MINOR.PATCH 格式。

策略 3：Native 版本约束

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

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

在 channel 上启用 metadata targeting

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

上传时设置最低 Native 版本

上传 bundle 时，请指定允许接收该 bundle 的最低 Native 版本：

# 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 根据 Native 包的兼容性自动设置下限：

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

工作原理

通过元数据策略，如果设备的 Native Baseline (version_build) 低于 Bundle 的 min_update_version 版本，则会跳过更新。只有处于该版本或更高版本的设备才会接收更新。详情请参阅 兼容性 来实现 --auto-min-update-version 。

使用场景

1. 需要新的 Native Plugin

   # 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"

策略 4：防止自动降级

防止用户接收到比当前 Native Build 版本更旧的 bundle。

在 Channel Settings 中启用

在 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
• 结果：更新被拦截（版本回退）

适用场景：

• 用户通过 App Store 手动安装了更高版本
• 需要确保用户始终使用最新的安全补丁
• 想要防止回归 Bug

策略 5：设备级定向

为特定设备或用户组覆盖 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' })
  }
}

Dashboard 设备覆盖

在 Capgo dashboard 中：

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

测试更新

在向所有用户全量发布更新之前，用 device overrides 在自己的设备上测试。

完整的 AppFlow 风格工作流

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

1. 初始设置 (App v1.0.0)

# 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)

# 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. 向两个版本推送更新

# 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"

4. 监控版本分布情况

使用 Capgo dashboard 追踪：

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

5. 弃用旧版本

当 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 优先级

当存在多个 Channel 配置时，Capgo 遵循以下优先级顺序：

1. 设备覆盖 (Device Override) （Dashboard 或 API）- 优先级最高，且在 Device Override UI 中可见
2. 本地插件 Channel 通过 setChannel() - 仅存储在设备上，不会在 Device Override UI 中显示
3. defaultChannel 在 capacitor.config.ts 中
4. 默认 Channel （Cloud 设置）- 优先级最低

优先级示例

如果用户的 App 拥有 defaultChannel: 'v2' 但你将其设备覆盖为 'beta' 在 dashboard 中，他们将接收来自 'beta' Channel。

Device Override UI 仅列出通过 dashboard 或 Public API 设置的覆盖项。调用 setChannel() 来自 app 的请求会向后端验证 channel，然后将其存储在设备本地。

最佳实践

1. 务必为大版本设置 defaultChannel

// ✅ 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

2. 使用语义化版本控制 (Semantic Versioning)

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. 维护独立分支

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. 发布前进行测试

# 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

5. 监控版本分发情况

定期检查您的 dashboard：

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

与 Ionic AppFlow 的对比

对于正在从以下产品迁移的团队： Ionic AppFlow以下是 Capgo 的版本定向功能对比：

功能	Ionic AppFlow	Capgo
基于版本的路由	根据 Native 版本自动匹配	通过以下方式自动实现 defaultChannel + 多种策略
语义化版本控制 (SemVer)	基础支持	进阶支持 --disable-auto-update (主版本/次版本/修订号)
Native 版本约束	在 AppFlow dashboard 中手动配置	内置 --min-update-version / --auto-min-update-version 配合 metadata channels 使用
频道管理	Web UI + CLI	Web UI + CLI + API
设备覆盖	设备级控制有限	通过 Dashboard/API 实现完全控制
防止自动降级	是	是，通过 --no-downgrade
多版本维护	手动管理分支/Channel	基于 Channel 优先级自动管理
自托管	否	支持（完全控制）
版本分析	基础版	详细的各版本指标

媲美并超越 AppFlow

Capgo 提供 AppFlow 所具备的所有版本定向功能 以及更强大的控制机制。如果你之前依赖 AppFlow 的自动版本匹配，你会发现 Capgo 在保持同样安全性的同时，提供了更高的灵活性。

故障排除

用户收不到更新

请检查以下各项：

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. 设备覆盖 (Device Override): 检查设备是否设置了手动覆盖

   • Dashboard → Devices → 搜索设备 → 检查 channel/version

Bundle 推送到了错误的版本

1. 检查 defaultChannel: 确保配置了正确的 channel capacitor.config.ts
2. 检查 Bundle Upload: 验证 bundle 是否已上传至目标 channel
3. 检查最小更新版本 (min update version): 确认 --min-update-version (或 --auto-min-update-version) 已设置，且该 channel 使用 --disable-auto-update metadata

影响旧版本的 Breaking Changes

1. 立即修复方案: 将受影响的设备覆盖到安全 bundle
   • Dashboard → 设备 → 批量选择 → 设置版本
2. 长期修复方案: 创建版本化 channel 并维护独立分支
3. 预防措施: 在发布更新前，务必在代表性设备上进行测试

从 Ionic AppFlow 迁移

如果您正在从 Ionic AppFlow进行迁移，Capgo 的版本定向功能非常相似，且具备更高的灵活性：

概念映射

AppFlow 概念	Capgo 对应项	备注
部署频道	Capgo 通道	核心理念一致，功能更强大
锁定 Native Build 版本	--min-update-version / --auto-min-update-version	更精细的控制粒度
Channel 优先级	Channel 优先级顺序 (override → cloud → default)	更透明的优先级机制
部署目标	Channel + semver 控制	支持多种策略
生产环境频道	production channel (或任意名称)	灵活的命名方式
基于 Git 的部署	从分支 CLI bundle upload	相同的流程
自动版本匹配	defaultChannel + 版本约束	支持多种策略，功能更强

AppFlow 用户的核心区别

1. 更强的控制力: Capgo 提供多种可组合的策略（channels、semver、native version）
2. 更好的可视化: Dashboard 可查看版本分布和兼容性问题
3. API 访问权限: 实现对版本定向的完全程序化控制
4. 自托管: 可选择运行具有相同版本逻辑的自有更新服务器

迁移步骤

1. 映射您的 AppFlow channels 至 Capgo channels（通常为 1:1）
2. 设置 defaultChannel 中的 capacitor.config.ts 针对每个主版本
3. 配置 semver 规则 如果你想在版本边界实现自动拦截
4. 上传特定版本的 bundle 使用 --min-update-version （channel 必须使用 metadata 策略）
5. 监控版本分发情况 在 Capgo dashboard 中

完整迁移指南

有关包括 SDK 替换和 API 映射在内的完整迁移说明，请参阅 AppFlow 迁移至 Capgo 指南.

高级模式

按版本进行渐进式发布

// 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' })
  }
}

按版本配置 Feature Flags

// 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()
  }
}

跨版本 A/B 测试

// 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. Native 版本约束: 为 bundle 设置最低 Native 版本要求
4. 防止自动降级: 绝不向更高版本的 Native 环境推送旧版 bundle
5. 设备覆盖 (Device Overrides): 用于测试和定向投放的手动控制

通过结合这些策略，你可以实现类似 AppFlow 的自动更新推送，并获得更高的灵活性与控制力。请根据你应用的定版本和部署工作流选择最合适的方法。

有关特定功能的更多详情：

• 破坏性变更指南 - 详细的 Channel 版本管理策略
• Channel 管理 - 完整的 Channel 配置参考
• 更新行为 - Native 版本延迟与条件

从版本定向继续

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