版本目标

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

从Ionic AppFlow迁移?

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

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

Capgo’s version targeting system allows you to:

• 概述部分 根据用户的原生应用版本为用户提供内容
• 防止破坏性更改 防止不兼容的应用版本接收更新
• 管理多个应用版本 同时无需复杂逻辑
• 无缝推送更新 到特定用户群

为什么版本目标定位很重要（尤其是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 的交付模型类似。 示例场景

示例场景

• (100,000 名用户) → 基于渠道的版本路由是管理重大变更和主要版本更新的推荐方法。它类似于 AppFlow 的交付模型。 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

自动路由

When users open the app, they automatically connect to their designated channel based on the defaultChannel installed app bundle. No JavaScript code changes required!

Benefits

• Zero code changes - Channel routing happens automatically
• - Each version has its own update pipeline - Flexible targeting
• - Push updates to specific version groups - Safe rollouts
• - Breaking changes never reach incompatible versions Benefits

策略 2：语义版本控制

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

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

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

应用程序版本的用户

• 将接收更新直到 1.2.3 版本 1.9.9
• 用户将不会 不会 不会自动接收版本 2.0.0 防止破坏性更改到达较旧的本机__CAPGO_KEEP_0__
• Prevents breaking changes from reaching older 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

Granular Control Options

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

策略 3：本机版本约束

在每个捆绑包中指定一个最小的本机应用程序版本（min_update_version）以便Capgo仅将其分发给设备，其本机二进制文件足够新。

本策略使用 渠道 元数据--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 将跳过更新。仅在该版本或更高版本的设备上接收更新。请参见 兼容性 for --auto-min-update-version details.

使用场景

1. New Native Plugin Required

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli@latest bundle upload \
     --channel production \
     --min-update-version "2.0.0"

2. Breaking Native API Changes

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

Strategy 4: Auto-Downgrade Prevention

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

在频道设置中启用。

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

仪表盘设备覆盖

在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.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
    }
  }
};

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

顺序示例

如果用户的应用程序具有 defaultChannel: 'v2' 但您覆盖了用户的设备到 'beta' 在控制台中设置的频道。 'beta' 仅从控制台或公共__CAPGO_KEEP_0__设置的设备覆盖UI仅列出覆盖项。调用

The Device Override UI only lists overrides set from the dashboard or Public API. Calling setChannel() 最佳实践

标题为“最佳实践”

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

# ✅ 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
设备覆盖	受限的设备级控制	通过 Dashboard/API 进行全控制
防止自动降级	是	是通过 --no-downgrade
多版本维护	手动分支/频道管理	自动（频道优先）
自主托管	否	是（完全控制）
版本分析	基本	详细每个版本指标

AppFlow 平台和超越

Capgo 提供 所有版本目标功能 所有 AppFlow 提供的功能，且具有额外的控制机制。如果您依赖 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 defaultChannel: 确保正确的频道在 capacitor.config.ts
2. Check Bundle Upload: 验证包是否已上传到预期的频道
3. Inspect min update version: 确认 --min-update-version (或 --auto-min-update-version)已设置并且频道使用 --disable-auto-update metadata

Breaking Changes Affecting Old Versions

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

从Ionic AppFlow迁移

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

Long-term Fix

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

AppFlow 用户的关键区别

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

迁移步骤

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

完整迁移指南

有关完整迁移指南，包括SDK替换和API映射，请参见 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. Channel-Based Routing: 不再向新版原生版本发送旧包
5. 设备覆盖: 用于测试和目标的手动控制

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

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

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

继续从版本目标

如果您正在使用 版本目标定位 与其连接 渠道 在渠道中 在渠道中 在渠道中 Beta测试解决方案 在Beta测试解决方案中 for the product workflow in Beta Testing Solution, and for the product workflow in Beta Testing Solution, and 版本目标解决方案 为版本目标解决方案中的产品工作流提供解决方案。