版本目标

本指南将解释如何自动将最新兼容的包传递给基于其本机应用程序版本的用户 类似于Ionic AppFlow的方法. This ensures simplified update management and faster rollouts while preventing compatibility issues.

从Ionic AppFlow迁移?

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

概述

Capgo的版本目标系统允许您:

• 自动传递兼容更新 根据用户的原生应用版本为用户提供内容
• 防止破坏性更改 防止不兼容的应用版本接收到更新
• 管理多个应用版本 同时不需要复杂的逻辑
• 无缝地发布更新 向特定用户群发布更新

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

如果您熟悉 Ionic AppFlow,您就知道确保用户只接收兼容更新是多么重要。 AppFlow自动将实时更新包匹配到原生应用版本，从而防止向较旧的原生code应用程序传递不兼容的JavaScript

Capgo 提供相同的安全保证, 还有额外的功能:

• 版本匹配的更细致的控制
• 多种策略（渠道、语义版本、原生约束）
• 更好的版本分布可视化
• API 和 CLI 与控制台管理一起控制

这种方法特别适用于以下情况:

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

如何工作

Capgo uses a multi-layered approach to match users with compatible updates:

1. __CAPGO_KEEP_0__ 使用多层级的方法来匹配用户与兼容的更新:原生版本约束
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

• App v1.x (100,000 users) → App v1.x (100,000 users) → 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 create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create 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

自动路由

当用户打开应用时，他们会自动连接到他们安装的应用程序包中指定的频道。无需进行任何JavaScript代码更改! defaultChannel in their installed app bundle. No JavaScript code changes required!

好处

• Zero code changes - 每个版本都有自己的更新管道
• - 可以推送特定版本组的更新 - 不会将破坏性更改推送给不兼容的版本
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

策略 2：语义版本控制

使用 Capgo 内置的 语义版本控制 防止版本边界内的更新。

禁用重大版本之间的自动更新

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

应用程序版本的用户将

• 接收更新至 1.2.3 __CAPGO_KEEP_0__ 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) on each bundle so Capgo only delivers it to devices whose native binary is new enough.

，以便__CAPGO_KEEP_0__仅将其分发给设备，其本机二进制文件足够新。 本方案使用 元数据--disable-auto-update metadata策略（）以及 --min-update-version 或 --auto-min-update-version __CAPGO_KEEP_0__ --native-version CLI flag.

启用渠道元数据目标

# 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 详细信息 使用场景 使用场景 --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

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

在频道设置中启用。

在Capgo控制台中：

1. 前往 频道 选择您的频道
2. 启用 在本机下禁用自动降级
3. 保存更改

或通过CLI：

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

示例

• 用户设备：原生版本 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' })
  }
}

仪表盘设备重写

In the Capgo dashboard:

1. 设备 → 找到设备 点击
2. 在__CAPGO_KEEP_0__仪表盘中： 设置频道 或 选择频道或版本
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.config.ts

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

Section titled “2. Release Breaking Change (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
    }
  }
};

Section titled “3. Push Updates to Both Versions”

# 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. 默认渠道 (Cloudflare 设置) - 优先级最低

顺序示例

如果用户的应用程序具有 defaultChannel: 'v2' 但是您可以覆盖他们的设备以 'beta' 在控制台中设置的设备覆盖将接收来自 'beta' 频道的更新。

The Device Override UI only lists overrides set from the dashboard or Public API. Calling setChannel() __CAPGO_KEEP_0__ 公开调用

从应用程序调用验证频道与后端，然后在设备上存储。

标题为“最佳实践”的部分

// ✅ 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 Ionic AppFlow，下面是Capgo的版本目标与之相比:

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

AppFlow 平台和超越

Capgo 提供 所有版本目标功能 AppFlow 提供的所有版本目标功能，plus 额外的控制机制。如果您依赖于 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. 检查 Bundle 上传: 验证包是否已上传到预期频道
3. 检查最小更新版本: 确认 --min-update-version (或 --auto-min-update-version)已设置并且频道使用 --disable-auto-update metadata

影响旧版本的重大更改

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

从Ionic AppFlow迁移

如果您正在从Ionic AppFlow迁移， 版本目标在__CAPGO_KEEP_0__中与Ionic AppFlow非常相似，但具有更好的灵活性：, version targeting works very similarly in Capgo, with improved flexibility:

标题：概念映射

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

AppFlow 用户的关键差异

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

迁移步骤

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

全Migration指南

有关完整的迁移说明，包括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样式的自动更新分发，具有更大的灵活性和控制。 选择最适合您的应用版本和部署流程的方法。

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

• Breaking Changes 指南 - 细致的渠道版本策略
• 渠道管理 - 完整的渠道配置参考
• 更新行为 - 原生版本延迟和条件

继续阅读：版本目标

如果您正在使用 版本目标 连接它与 渠道 渠道 渠道 渠道 产品工作流 产品工作流 产品工作流 产品工作流 版本目标解决方案 用于版本目标解决方案的产品工作流程。