版本目标

本指南解释了如何自动将最新兼容的包传递给用户，基于他们的本地应用程序版本， 类似于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 Ionic AppFlow AppFlow 迁移指南

概述

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

• 自动向基于本机应用程序版本的用户提供兼容更新 防止不兼容的应用程序版本接收破坏性更改
• 同时管理多个应用程序版本 无需复杂逻辑
• __CAPGO_KEEP_0__’s version targeting system allows you to: Automatically deliver compatible updates to users based on their native app version Prevent breaking changes from reaching incompatible app versions Manage multiple app versions simultaneously without complex logic
• 无缝升级 到特定用户群

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

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

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

• 对版本匹配的更细致的控制
• 多种策略（通道、语义版本号、原生约束）
• 更好的版本分布可视化
• API 和 CLI 控制着仪表盘管理

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

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

如何工作

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

1. 本机版本约束: 防止不兼容的本机版本接收捆绑包
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 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]

Strategy 1: Channel-Based Version Routing

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

示例场景

• App v1.x (100,000 名用户) → production channel
• App v2.x (50,000 名用户带有破坏性更改) → v2 channel
• 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: '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 __CAPGO_KEEP_0__ 更改! defaultChannel in their installed app bundle. No JavaScript code changes required!

步骤 3: 上传版本特定包

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

策略 2：语义版本控制

Use Capgo’s built-in 来防止跨版本边界的更新。 Strategy 2: Semantic Versioning Controls

Disable Auto-Update Across Major Versions

# 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
• 使用本地基准进行比较 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：本机版本约束

__CAPGO_KEEP_0__

为捆绑包指定最低原生版本要求，以防止将其分发到不兼容设备上。

使用原生版本延迟条件

当上传捆绑包时，您可以指定最低原生版本：

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

如何工作

在原生版本 1.x 设备上不会接收此捆绑包。只有在 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
• 频道包：版本结果

更新被阻止（将会降级）

• 这在以下情况下很有用：
• 用户手动从应用商店安装了更新的版本
• 您需要确保用户始终有最新的安全补丁

您想防止回归错误

为特定设备或用户组重写通道分配。

强制测试特定版本

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) - 优先级最高且可在设备覆盖 UI 中查看
2. 本地插件信道 通过 setChannel() -仅存储在设备上且不在设备覆盖 UI 中显示
3. __CAPGO_KEEP_0__.config.ts 中的默认信道 in capacitor.config.ts
4. (Cloudflare设置) - 优先级最低 (Dashboard or __CAPGO_KEEP_0__) - Highest priority and visible in the Device Override UI

优先级示例

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

The Device Override UI only lists overrides set from the dashboard or Public API. Calling 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. 在发布前进行测试

# 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的版本目标与以下有何区别：

功能	Ionic AppFlow	Capgo
基于版本的路由	根据本机版本自动	通过 defaultChannel + 多种策略
语义版本	基本支持	高级 --disable-auto-update (主/次/修订)
本机版本约束	在 AppFlow 控制台中进行手动配置	内置 --native-version CLI 的标志
渠道管理	Web UI + CLI	Web UI + CLI + API
设备覆盖	有限的设备级控制	通过 Dashboard/API 进行全控制
防止自动降级	是	是通过 --disable-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. 查看 defaultChannel: 确保通道正确 capacitor.config.ts
2. 检查包上传: 确认包已上传到预期的通道
3. 检查原生版本: 确认 --native-version 标志被正确使用

影响旧版本的重大变更

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

从 Ionic AppFlow 迁移

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

概念映射

__CAPGO_KEEP_0__ 等效	Capgo Equivalent	注意
发布渠道	Capgo 渠道	相同概念，更强大
原生版本锁定	--native-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. 上传版本特定的捆绑包 使用 --native-version 标志
5. 监控版本分布 在Capgo控制台

完成迁移指南

For complete migration instructions including SDK replacement and API mapping, see the 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-style自动更新交付,并且具有更大的灵活性和控制。选择最适合您的应用程序版本和部署工作流程的方法。

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

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

继续从版本目标

如果您正在使用 版本目标 来规划通道路由和分阶段发布，连接它与 频道 在频道中查看实现细节 频道 在频道中查看实现细节 频道 在频道中查看实现细节 Beta测试解决方案 查看产品工作流程在Beta测试解决方案中 版本目标解决方案 for the product workflow in Version Targeting Solution.