版本目标化

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

从 Ionic AppFlow 迁移?

If you’re coming from Ionic AppFlow, this guide is especially important for you. AppFlow automatically matched updates to native versions, and Capgo provides the same capability with even more control and flexibility. See the __CAPGO_KEEP_0__ 提供了相同的功能，并且具有更多的控制和灵活性。 请参阅 AppFlow 迁移指南

获取逐步迁移指示。

Capgo’s version targeting system allows you to:

• 自动为用户提供兼容的更新 根据用户的本机应用程序版本
• 防止破坏性更改 到不兼容的应用程序版本
• 同时管理多个应用程序版本 不需要复杂的逻辑
• 无缝地向特定用户段发布更新 为什么版本目标定位很重要（尤其是AppFlow用户）

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

Ionic AppFlow If you’re familiar with __CAPGO_KEEP_0__，您知道确保用户只接收兼容更新是多么重要吗？ AppFlow 自动匹配了实时更新包到本机应用程序版本，防止向较旧的本机 code 发送不兼容的 JavaScript。

Capgo 提供相同的安全保证, with additional features:

• 具有额外功能：
• 更细致的版本匹配控制
• 多个策略（通道、语义版本、native约束）
• API and CLI control alongside dashboard management

__CAPGO_KEEP_0__ 和 __CAPGO_KEEP_1__ 控制与仪表盘管理

• 这种方法在以下情况下尤其有用：
• 您有用户在应用程序的不同主要版本上（例如 v1.x、v2.x、v3.x）
• You want to prevent newer bundles from breaking older native code
• 您希望防止新包破坏较旧的本机 __CAPGO_KEEP_0__
• You’re migrating from AppFlow 并且希望保持相同的更新安全性

How It Works

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

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

版本匹配流程

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用户带有破坏性更改) → 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 清晰的分离
• - 每个版本都有自己的更新管道 灵活的目标
• - 将更新推送到特定版本组 安全的滚动发布
• Zero __CAPGO_KEEP_0__ changes - 不兼容版本不会接收到破坏性变化

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

语义版本控制所需

This strategy only works if you follow semantic versioning (semver) for your app versions. Ensure your version numbers follow the MAJOR.MINOR.PATCH format.

Strategy 3: Native Version Constraints

Specify minimum native version requirements for bundles to prevent delivery to incompatible devices.

在上传包时，您可以指定最低的原生版本：

Terminal window

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

如何工作

仅 2.0.0+ 设备才能接收到此捆绑包。对于需要新本机 API 或插件的更新来说，这是理想的选择。

使用场景

1. 需要新本机插件

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

策略 4：防止自动降级

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

在频道设置中启用

在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. 使用特定的频道或捆绑版本覆盖
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: 'atBackground',
      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: 'atBackground',
      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. 废弃旧版本

当 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) - 优先级最高
2. 云覆盖 通过 setChannel() 呼叫
3. 默认频道 在 capacitor.config.ts 中
4. 默认频道 (Cloud 设置) - 优先级最低

优先级示例

如果用户的应用程序有 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, here’s how Capgo’s version targeting compares:

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

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. 检查包上传: 验证包是否上传到正确的渠道
3. 检查原生版本: 确认标志是否使用正确 --native-version 影响旧版本的重大变更

影响旧版本的重大变更

1. Check Bundle Upload: Override affected devices to safe bundle
   • 仪表盘 → 设备 → 批量选择 → 设置版本
2. 长期修复: Create versioned channels and maintain separate branches
3. : 预防措施: 在代表性设备上始终测试更新之前进行滚动

从 Ionic AppFlow 迁移

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

Migration from Ionic AppFlow

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

AppFlow 用户的关键差异

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

迁移步骤

1. 映射 AppFlow 通道 到 Capgo 通道（通常 1:1）
2. 设置 defaultChannel 在 capacitor.config.ts 每个主要版本
3. 配置 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 提供多种版本特定更新分发策略：

1. 基于频道的路由：通过 defaultChannel
2. 语义版本控制：防止更新跨越主/次/修订版本边界
3. 原生版本约束: Require minimum native version for bundles
4. Auto-Downgrade Prevention: Never deliver older bundles to newer native versions
5. Device Overrides: 手动控制测试和目标

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

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

• Breaking Changes Guide -详细的通道版本策略
• Channel Management -完整的通道配置参考
• Update Behavior - 原生版本延迟和条件

从版本目标继续

如果您正在使用 版本目标 来规划渠道路由和阶段性发布，连接它与 渠道 查看渠道的实施细节在 渠道 查看渠道的实施细节在 渠道 查看渠道的实施细节在 Beta 测试解决方案 __CAPGO_KEEP_0__ 版本目标解决方案 __CAPGO_KEEP_0__