版本目标定位

本指南解释了如何自动将最新兼容的捆绑包交付给用户，基于他们的本机应用程序版本， 类似于 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的版本目标系统允许您：

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

如果您熟悉

__CAPGO_KEEP_0__的版本目标系统允许您： ionic AppFlow您知道确保用户只接收兼容更新是多么重要吗？AppFlow会自动匹配实时更新包到原生应用版本，防止向较旧的原生code传递不兼容的JavaScript。

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

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

这种方法在以下情况下尤其有用

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

如何工作

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

1. 原生版本约束:防止不兼容的原生版本接收捆绑包
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 (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 - 每个版本都有自己的更新管道
• - 可以灵活地针对特定版本组推送更新 __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__
• 安全发布 - 不兼容版本的Breaking changes不会到达

策略2：语义版本控制

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

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

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

这意味着：

• app版本用户 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

Semantic Versioning Required

只有遵循语义版本控制（semver）策略时，这种策略才会生效。确保您的应用程序版本号遵循语义版本控制的格式。 Strategy 3: Native Version Constraints 策略 3：原生版本约束 MAJOR.MINOR.PATCH 为捆绑包指定最低原生版本要求，以防止将其分发到不兼容的设备。

Using nativeVersion Delay Condition

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

__CAPGO_KEEP_0__

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

如何工作

仅在 2.0.0+ 设备上才能接收此捆绑包。1.x 设备将不会接收此捆绑包。这是为了更新所需的新本机 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样式工作流

以下是所有策略的完整示例：

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. 默认通道 在 capacitor.config.ts 中
4. 默认通道 (Cloud 设置) - 优先级最低

优先级示例

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

设备覆盖 UI 只列出从控制台或公共 API 中设置的覆盖。 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. 在发布前进行测试

# 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__	基于版本的路由	Capgo
Should you deprecate old channels?	For teams migrating from	自动化 defaultChannel + 多种策略
语义版本	基本支持	高级 --disable-auto-update (主版本/次版本/修订版本)
原生版本约束	在 AppFlow 控制台中手动配置	内置 --native-version 标志在 CLI 中
频道管理	Web UI + CLI	Web UI + CLI + API
设备覆盖	受限设备级控制	Full control via Dashboard/API
防止自动降级	是	是通过 --disable-downgrade
多版本维护	手动分支/频道管理	自动使用频道优先级
自主托管	否	是 (完全控制)
版本分析	基本	详细的每个版本指标

AppFlow 平衡和超越

Capgo 提供 所有版本目标能力 AppFlow 提供的所有版本匹配能力，plus 额外的控制机制。如果您依赖 AppFlow 的自动版本匹配，您会发现 Capgo 等同于安全性，具有更多灵活性。

故障排除

用户未接收更新

检查以下内容：

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 旗帜被正确使用

影响旧版本的重大变更

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

从Ionic AppFlow迁移

如果您正在从 Ionic AppFlow, version targeting works very similarly in Capgo, with improved flexibility:

版本目标功能在 __CAPGO_KEEP_0__ 中与原有功能非常相似，但功能更加灵活：

标题：概念映射	Capgo Equivalent	__CAPGO_KEEP_0__ 等价
注意	Capgo Channel	__CAPGO_KEEP_0__ 频道
相同概念，功能更强大	--native-version flag	更细致的控制
渠道优先级	渠道优先级（覆盖 → 云 → 默认）	更透明的优先级
部署目标	渠道 + semver 控制	可用多种策略
生产渠道	production 渠道（或任意名称）	灵活的命名
基于 Git 的部署	CLI 分支上传	相同的工作流程
自动版本匹配	defaultChannel +版本约束	多种策略增强

AppFlow 用户的关键差异

1. 更多控制: Capgo 给您多种策略（通道、semver、native 版本）可组合
2. 更好的可见性: 版本分布和兼容性问题的仪表盘
3. API 访问: 全程控制版本目标
4. : 自建主机: 自建更新服务器，同样支持版本逻辑

: 升级步骤

1. : 将 AppFlow 通道映射到 __CAPGO_KEEP_0__ 通道（通常 1:1） to Capgo channels (usually 1:1)
2. : 在 defaultChannel : 为每个主要版本 capacitor.config.ts : 配置 semver 规则
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 provides multiple strategies for version-specific update delivery:

1. 按版本逐步发布: 自动版本分离 via defaultChannel
2. Semantic Versioning: 防止更新跨越主/次/修订版本边界
3. Native Version Constraints: 为捆绑包要求最低的原生版本
4. Auto-Downgrade Prevention: 永远不向新版原生版本交付旧捆绑包
5. Device Overrides: 手动控制测试和目标

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

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

• Breaking Changes Guide - Channel 版本控制策略详细
• Channel 管理 - Channel 配置参考
• 更新行为 - 原生版本延迟和条件

从版本目标继续

如果您正在使用 版本目标 来规划渠道路由和分阶段发布，连接它与 渠道 来获取渠道实施细节 频道 关于频道的实现细节 频道 关于频道的实现细节 Beta 测试解决方案 用于 Beta 测试解决方案的产品工作流程 版本目标解决方案 用于版本目标解决方案的产品工作流程