版本目标

本指南解释了如何自动将最新兼容的捆绑包传递给用户，基于他们的本机应用程序版本，类似于 Ionic AppFlow 的方法。 基于本机应用程序版本自动传递最新兼容的捆绑包给用户的指南 . 这样可以简化更新管理和加快发布速度，同时防止兼容性问题。

从Ionic AppFlow迁移?

如果您从 Ionic AppFlow 迁移过来，这个指南对您尤其重要。 AppFlow 自动匹配更新到原生版本，而 Capgo 提供了相同的功能并且具有更多的控制和灵活性。 请参阅 AppFlow 迁移指南 Overview

Overview

Capgo的版本目标系统允许您

• 基于用户的原生应用版本 防止破坏性更改
• __CAPGO_KEEP_0__’s version targeting system allows you to: 避免不兼容的应用版本
• 管理多个应用版本 同时管理多个应用版本
• 无缝升级 向特定用户群推送更新

为什么版本目标定位很重要（尤其是AppFlow用户）

如果您熟悉 Ionic AppFlow,您就知道如何确保用户只接收兼容的更新。 AppFlow自动匹配live update包到本机应用版本，防止向较旧的本机code推送不兼容的JavaScript。

Capgo提供相同的安全保证,并且具有额外的功能：

• 版本匹配的更细致的控制
• 多种策略（渠道、SemVer、原生约束）
• 版本分布的更好可见性
• API 和 CLI 控制与仪表盘管理

这种方法尤其适用于以下情况：

• 您有不同主版本的用户（例如 v1.x、v2.x、v3.x）
• 您需要维护向后兼容性，同时推出破坏性更改
• 您想防止新版本的包破坏旧的原生code
• 您正在逐渐从一个版本迁移到另一个版本
• 您正在从 AppFlow 迁移 并且希望维持相同的更新安全性

如何工作

Capgo 使用多层次的方法来匹配用户与兼容的更新:

1. 原生版本约束:防止不兼容的原生版本接收更新包
2. 渠道路由:将不同应用版本路由到不同的更新渠道
3. 语义版本控制:自动阻止跨主版本/次版本/修订版本的更新
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]

策略 1：基于频道的版本路由

这是 推荐的方法 用于管理重大更改和主要版本更新。它与 AppFlow 的交付模型类似。

示例场景

• App v1.x (100,000 名用户) → production 频道
• App v2.x (50,000名用户的重大更新) → v2 频道
• App v3.x (10,000 个 beta 用户) → v3 频道

实施

步骤 1：为每个主要版本配置频道

// 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 步：创建频道

# 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 步：上传版本特定包

# 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

自动路由

当用户打开应用程序时，他们会自动连接到他们安装的应用程序包中指定的频道，基于 defaultChannel 在他们安装的应用程序包中。无需进行任何 JavaScript code 更改!

优势

• 零 code 变更 - 通道路由会自动发生
• 清晰的分离 - 每个版本都有自己的更新管道
• 灵活的目标 - 将更新推送到特定版本组
• 安全的滚动 - 不兼容版本的破坏性更改永远不会到达

策略 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

这意味着：

• 应用程序版本的用户 1.2.3 将接收更新到 1.9.9
• 用户将 不会 接收版本 2.0.0 自动
• 防止向较旧的本机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

语义版本控制必需

只有遵循语义版本控制（semver） 此策略才有效 为您的应用程序版本。确保您的版本号遵循 MAJOR.MINOR.PATCH 格式。

策略 3：本机版本约束

指定每个捆绑包的最小本机应用程序版本（min_update_version）以便Capgo仅将其分发到具有足够新本机二进制的设备。

本机元数据 策略（ ）--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

在上传时设置最低原生版本

当上传一个捆绑包时，请传递可能接收它的最低原生版本：

# 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

如何工作

使用元数据策略，设备的本地基线（version_build）低于捆绑包的 min_update_version ）的设备将跳过更新。仅在该版本或更高版本的设备上接收更新。请参见 兼容性 for --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. 破坏性本地 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：自动降级防护

防止用户接收比他们当前本地版本更旧的捆绑包。

在频道设置中启用

In the Capgo 控制台:

1. 前往 频道 context:Capgo发布频道功能名称。页面/区域：Capgo解决方案营销页面。角色：短UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`解决方案白标签视觉单元2值` (Solutions White Label Visual Cell2 Value)。
2. → 选择您的频道 启用
3. “在原生下禁用自动降级”

通过 CLI

npx @capgo/cli@latest channel set production --no-downgrade

复制到剪贴板中：Example

• 用户设备：原生版本 1.2.5
• 频道包：版本 1.2.3
• 结果: 更新被阻止（将会是降级)

这在以下情况下很有用:

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

策略 5：设备级别目标

为特定设备或用户组覆盖频道分配

强制指定版本进行测试

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仪表盘中：

1. 前往 设备 →找到设备
2. 点击 设置频道 或 设置版本
3. 使用特定的渠道或捆绑包版本覆盖
4. 设备将从覆盖源接收更新

测试更新

使用设备覆盖来在所有用户之前在您的设备上测试更新。

完整的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.配置文件

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控制台来跟踪:

• v1 和 v2 用户数量
• 每个版本的包装采用率
• 每个版本的错误或崩溃率

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)

频道顺序

当存在多个渠道配置时，Capgo遵循以下顺序:

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

优先级示例

如果用户的应用程序具有 defaultChannel: 'v2' 但您可以覆盖他们的设备以 'beta' 在仪表板中， 'beta' 频道。

设备重写 UI 只会列出从控制台或公共 API 中设置的重写。 setChannel() 从应用程序调用

从应用程序调用

最佳实践

// ✅ 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. 使用语义版本

# ✅ 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. 监控版本分布

定期检查您的仪表板：

• 用户是否正在升级到新版本的原生版本?
• 老版本是否仍然获得高流量?
• 您是否应该弃用旧频道?

与Ionic AppFlow的比较

对于从Ionic AppFlow迁移的团队来说， 这里是__CAPGO_KEEP_0__版本目标的比较：,Capgo的版本目标与以下有所不同：

功能	ionic AppFlow	Capgo
版本依赖路由	基于原生版本的自动	通过 defaultChannel + 多种策略
语义版本	基本支持	带有 --disable-auto-update (主/次/修订)
原生版本约束	在 AppFlow 控制台中进行手动配置	内置 --min-update-version / --auto-min-update-version 带有元数据频道
频道管理	Web UI + CLI	Web UI + CLI + API
设备覆盖	受限设备级控制	通过控制台/API
预防自动降级	是	是通过 --no-downgrade
多版本维护	手动分支/频道管理	自动化（频道优先）
自主托管	否	是（完全控制）
版本分析	基本	详细每个版本指标

AppFlow 平台和超越

Capgo 提供 所有版本目标功能 与 AppFlow 提供的功能相比，Live Update 还提供了更多的控制机制。如果您依赖 AppFlow 的自动版本匹配功能，您将发现 Capgo 与更大的灵活性一样安全。

故障排除

用户未接收更新

请检查以下内容：

1. 频道分配: 确认设备已切换到正确频道

   const channel = await CapacitorUpdater.getChannel()
   console.log('Current channel:', channel)

2. 版本约束: 检查是否有本机版本要求

   • : 仪表盘 → 包 → 检查 "本机版本" 列

3. Semver 设置: 验证渠道的 disable-auto-update 设置

   npx @capgo/cli channel list

4. 设备覆盖: 检查设备是否有手动覆盖

   • 仪表板 → 设备 → 搜索设备 → 检查渠道/版本

捆绑包传递到错误版本

1. Review 默认渠道: 确保正确的渠道在 capacitor.config.ts
2. 检查包上传: 确认包已上传至指定渠道
3. 检查最小更新版本: 确认 --min-update-version (或 --auto-min-update-version: 确认渠道已设置并且渠道使用 --disable-auto-update metadata

影响旧版本的重大变更

1. 立即修复: 强制受影响设备使用安全包
   • 仪表板 → 设备 → 批量选择 → 设置版本
2. 长期修复: 创建版本化通道并维护独立分支
3. 防护: 在发布前始终在代表设备上测试更新

从Ionic AppFlow迁移

如果您正在从Ionic AppFlow迁移，版本目标在__CAPGO_KEEP_0__中与改进的灵活性非常相似： 概念映射,版本目标定向在 Capgo 中与Live Update类似，但具有更好的灵活性。

__CAPGO_KEEP_0__等效项

Prevention	Capgo 等效	注意事项
发布频道	Capgo频道	相同概念，更加强大
原生版本锁定	--min-update-version / --auto-min-update-version	更细致的控制
频道优先级	频道优先级（覆盖 → 云 → 默认）	更透明的优先级
部署目标	频道 + semver 控制	可用多种策略
生产环境频道	production 频道（或任意名称）	灵活命名
基于Git的部署	CLI 分支上传包	相同工作流程
自动版本匹配	defaultChannel + 版本约束	多策略增强

AppFlow用户的关键差异

1. 更多控制: Capgo 给你多种策略（渠道、semver、原生版本）可以组合
2. 更好的可见性: 版本分布和兼容性问题的仪表板显示
3. API 访问: 对版本目标有完全的程序控制
4. 自主托管: 使用相同的版本逻辑运行自己的更新服务器

迁移步骤

1. 映射 AppFlow 渠道 到 Capgo 渠道（通常 1:1）
2. Set defaultChannel 在 capacitor.config.ts 每个主要版本
3. 配置semver规则 如果您希望在版本边界处自动阻止
4. 上传版本特定包 使用 --min-update-version (频道必须使用元数据策略)
5. 监控版本分布 在Capgo控制台

完成迁移指南

有关完整迁移指南，包括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' })
  }
}

版本级特性标志

// 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. 渠道路由: 通过语义版本号实现自动版本分离 defaultChannel
2. 语义版本号: 防止更新跨越主版本/次版本/修订版本
3. 原生版本约束: 为捆绑包要求最低原生版本
4. 自动降级防止: 永远不向新原生版本分发旧捆绑包
5. 设备覆盖: 手动控制测试和目标

通过结合这些策略，您可以实现AppFlow样式的自动更新分发，具有更大的灵活性和控制。选择最适合您的应用版本和部署工作流程的方法。

有关特定功能的更多详细信息：

• 更新指南 -详细的频道版本策略
• 频道管理 -完整的频道配置参考
• 版本目标 -原生版本延迟和条件

继续从版本目标定位

如果您正在使用 版本目标定向 为计划频道路由和阶段性发布，连接它 频道 为频道功能的实现细节 频道 为频道功能的实现细节 频道 为频道功能的实现细节 Beta测试解决方案 为Beta测试解决方案中的产品工作流 版本目标定向解决方案 为版本目标定向解决方案中的产品工作流