版本目标

本指南解释了如何基于用户的本机应用程序版本自动交付最新兼容的捆绑包， 类似于 Ionic AppFlow 的方法. 这确保了简化的更新管理和更快的发布，同时防止了兼容性问题。

从Ionic AppFlow迁移?

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

Overview

Capgo’s version targeting system allows you to:

• 提供兼容的更新 防止破坏性更改
• Prevent breaking changes 避免不兼容的应用程序版本
• 管理多个应用程序版本 同时无需复杂逻辑
• 无缝推出更新 到特定用户群

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

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

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

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

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

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

如何工作

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

1. Native Version Constraints: 防止不兼容的本机版本接收更新包
2. Channel-Based Routing: 将不同应用程序版本路由到不同的更新通道
3. Semantic Versioning Controls: 自动阻止更新跨越主/次/修订版本边界
4. Device-Level Overrides: 目标特定设备或用户组

Version Matching Flow

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

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

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

示例场景

• App v1.x (100,000 名用户) → production 通道
• App v2.x (50,000 users with breaking changes) → v2 频道
• App v3.x (10,000 beta users) → 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: true,
      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: true,
      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: true,
      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

自动路由

当用户打开应用程序时，他们会自动连接到他们指定的频道，基于 defaultChannel in their installed app bundle. No JavaScript code changes required!

优势

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

策略 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 自动更新
• 防止向较旧的本机 code 发送破坏性更改

细粒度控制选项

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (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：本机版本约束

为捆绑包指定最低本机版本要求，以防止将其交付给不兼容设备。

使用nativeVersion延迟条件

当上传一个捆绑包时，您可以指定一个最小的native版本：

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

如何工作

在native版本1.x的设备上不会接收到这个捆绑包。只有在2.0.0+的设备上才会接收到它。这对于需要新native API或插件的更新来说是完美的。

用例

1. 需要新native插件

   # Bundle needs Camera plugin added in v2.0.0
   npx @capgo/cli bundle upload --native-version "2.0.0"

2. 破坏本机API的更改

   # Bundle uses new Capacitor 6 APIs
   npx @capgo/cli bundle upload --native-version "3.0.0"

3. 渐进式迁移

   # Test bundle only on latest native version
   npx @capgo/cli bundle upload \
     --channel beta \
     --native-version "2.5.0"

防止自动降级

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

在频道设置中启用

在 Capgo 控制台中：

1. 前往 频道 → 选择您的频道
2. 启用 “在原生下禁用自动降级”
3. 保存更改

或通过 CLI:

npx @capgo/cli channel set production --disable-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. Override with specific channel or bundle version
4. 设备将从覆盖的源接收更新

测试更新

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

完整的AppFlow-Style工作流

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

终端窗口

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

capacitor.config.ts

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

2. 发布版本更新（App v2.0.0）

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-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: true,
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. 同时推送更新到两版本

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. 监控版本分布

使用 Capgo 面板来跟踪：

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

第 5 章：废弃旧版本

终端窗口

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

第 5 章：废弃旧版本

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

1. 设备覆盖 (控制台或API) - 最高优先级
2. 云覆盖 通过 setChannel() 调用
3. 默认通道 在capacitor.config.ts中
4. 默认通道 (云设置) - 低优先级

优先顺序示例

如果用户的应用程序有 defaultChannel: 'v2' 但您覆盖了他们的设备 'beta' 在仪表板中，他们将从 'beta' 频道接收更新。

最佳实践

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. 在发布前进行测试

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. 监控版本分布

定期检查您的仪表板：

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

与Ionic AppFlow的比较

从Ionic AppFlow迁移的团队，请参阅__CAPGO_KEEP_0__的版本目标功能 功能, here’s how Capgo’s version targeting compares:

__CAPGO_KEEP_0__	版本路由	与Ionic AppFlow相比，Capgo的版本目标功能
版本路由	基于本地版本的自动	通过 defaultChannel + 多种策略
语义版本	基本支持	高级 --disable-auto-update (主/次/修)
本地版本约束	在 AppFlow 控制台中进行手动配置	内置 --native-version 标志在 CLI
频道管理	Web UI + CLI	Web UI + CLI + API
设备覆盖	设备级别控制有限	通过控制台/API 完全控制
防止自动降级	是	是通过 --disable-downgrade
多版本维护	手动管理分支/频道	自动管理，频道优先
自主托管	否	是（完全控制）
版本分析	基本	详细的每个版本指标

AppFlow 平台和超越

Capgo 提供 所有版本目标功能 AppFlow 提供的功能，plus 额外的控制机制。如果您依赖于 AppFlow 的自动版本匹配，您将在 Capgo 中找到同样的安全性和更多的灵活性。

故障排除

__CAPGO_KEEP_0__

检查以下内容：

1. 频道分配: 确认设备位于正确频道

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

2. 版本约束: 检查包是否有原生版本要求

   • 仪表盘 → 包 → 检查“原生版本”列

3. 语义版本设置: 确认频道的 disable-auto-update 设置

   npx @capgo/cli channel list

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

   • 仪表盘 → 设备 → 搜索设备 → 检查频道/版本

捆绑包传递到错误版本

1. 查看defaultChannel: 确保频道正确 capacitor.config.ts
2. 检查捆绑包上传: 验证捆绑包上传到预期频道
3. 检查原生版本: 确认 --native-version flag 已经正确使用

影响旧版本的重大变更

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

从 Ionic AppFlow 迁移

如果您正在从 Ionic AppFlow,版本目标在 Capgo 中工作得非常相似，具有改进的灵活性：

概念映射

__CAPGO_KEEP_0__ 等效	Capgo Equivalent	发布频道
__CAPGO_KEEP_0__ 频道	Capgo Channel	迁移自 Ionic AppFlow
原生版本锁定	--native-version 标志	更细致的控制
渠道优先级	渠道优先级（override → 云 → 默认）	更透明的优先级
部署目标	渠道 + semver 控制	可用多种策略
生产渠道	production 渠道（或任意名称）	灵活的命名
基于 Git 的部署	CLI 分支上的打包上传	相同的工作流程
自动版本匹配	defaultChannel + 版本约束	多种策略增强

适用于 AppFlow 用户的关键区别

1. 更多控制: Capgo 提供多种策略（通道、语义版本、原生版本）可组合
2. 更好的可见性: 版本分布和兼容性问题在仪表盘中显示
3. API 访问: 完全控制版本目标的程序化控制
4. 自主托管: 使用相同的版本逻辑运行自己的更新服务器

迁移步骤

1. 将您的 AppFlow 通道映射到 __CAPGO_KEEP_0__ 通道（通常 1:1） to Capgo channels (usually 1:1)
2. 在 defaultChannel 为每个主要版本 capacitor.config.ts 配置 semver 规则
3. Configure semver 规则 如果您想在版本边界处自动阻止
4. 上传版本特定的捆绑包 使用 --native-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 provides multiple strategies for version-specific update delivery:

1. 基于通道的路由: 自动通过语义版本号分离 defaultChannel
2. 语义版本号: 防止跨主/次/修版本更新
3. 原生版本约束: 为捆绑包指定最低原生版本
4. 自动降级防止: 永远不向新原生版本发送旧捆绑包
5. 设备覆盖: 手动控制测试和目标

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

有关具体功能的更多详细信息：

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