版本定向
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
本指南介绍如何根据用户的原生应用版本,自动向用户下发最新的兼容 bundle, 与 Ionic AppFlow 的做法类似。这样既能简化更新管理、加快发布速度,又能避免兼容性问题。
概览
“概览”章节Capgo 的版本定向系统让你可以:
- 自动分发兼容更新 给原生应用版本匹配的用户
- 防止破坏性变更 波及不兼容的应用版本
- 同时管理多个应用版本 无需复杂逻辑
- 无缝发布更新 到特定用户群
为什么版本定向很重要(尤其是 AppFlow 用户)
章节标题:“为什么版本定向很重要(尤其是 AppFlow 用户)”如果你熟悉 Ionic AppFlow,你就会明白,确保用户只收到兼容更新有多重要。AppFlow 会自动将 live update bundle 与原生应用版本匹配,避免不兼容的 JavaScript 被下发到旧版原生 code。
Capgo 提供相同的安全保障,还提供以下额外功能:
- 更细粒度的版本匹配控制
- 多种策略(频道、semver、原生约束)
- 更清晰地了解版本分布
- API 和 CLI 与 Dashboard 管理协同工作
这种方法在以下场景中特别有用:
- 您的用户处于应用的不同主要版本(例如 v1.x、v2.x、v3.x)
- 您需要保持向后兼容性的同时,推出破坏性变更
- 您希望防止较新的 bundle 破坏较旧的 code 原生代码
- 您正在逐步将用户从一个版本迁移到另一个版本
- 您正在从 AppFlow 迁移 并希望保持相同的更新安全性
工作原理
标题为“工作原理”的章节Capgo 采用多层策略,将用户与兼容的更新进行匹配:
- 原生版本约束: 防止 bundle 被下发到不兼容的原生版本
- 基于 Channel 的路由: 将不同 App 版本路由到不同更新 Channel
- 语义化版本控制: 自动拦截跨 major/minor/patch 边界的更新
- 设备级覆盖: 针对特定设备或用户群
版本匹配流程
章节标题:“版本匹配流程”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:基于 Channel 的版本路由
章节标题:“策略 1:基于 Channel 的版本路由”这是 推荐的方法 用于管理破坏性变更和主要版本更新。它类似于 AppFlow 的交付模型。
示例场景
标题为“示例场景”的章节- App v1.x (100,000 用户)→
production渠道 - App v2.x (50,000 用户,包含破坏性变更)→
v2渠道 - App v3.x (10,000 名 Beta 用户)→
v3渠道
实现
“实现”章节步骤 1:为每个主要版本配置 Channel
标题为“步骤 1:为每个主要版本配置 Channel”的章节// capacitor.config.ts for version 1.x buildsimport { 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 buildsconst 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 buildsconst config: CapacitorConfig = { appId: 'com.example.app', appName: 'Example App', plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'v3', // Routes v3 users automatically } }};步骤 2:创建 Channel
标题为“第 2 步:创建 Channel”的章节# Create channels for each major versionnpx @capgo/cli channel add productionnpx @capgo/cli channel add v2npx @capgo/cli channel add v3
# Enable self-assignment so apps can switch channelsnpx @capgo/cli channel set production --self-assignnpx @capgo/cli channel set v2 --self-assignnpx @capgo/cli channel set v3 --self-assign步骤 3:上传特定版本的 Bundle
标题为“步骤 3:上传特定版本的 Bundle”# For v1.x users (from v1-maintenance branch)git checkout v1-maintenancenpm run buildnpx @capgo/cli bundle upload --channel production
# For v2.x users (from v2-maintenance or main branch)git checkout mainnpm run buildnpx @capgo/cli bundle upload --channel v2
# For v3.x users (from beta/v3 branch)git checkout betanpm run buildnpx @capgo/cli bundle upload --channel v3优势
标题为“优势”- 零 code 修改 - Channel 路由自动完成
- 清晰分离 - 每个版本都有独立的更新 pipeline
- 灵活定向 - 向指定版本组推送更新
- 安全发布 - Breaking changes 绝不会影响不兼容的版本
策略 2:语义化版本控制
章节标题:“策略 2:语义化版本控制”使用 Capgo 内置的 语义化版本控制功能 来防止更新跨越版本边界。
禁止跨大版本自动更新
章节标题:“跨大版本禁用自动更新”# Create a channel that blocks major version updatesnpx @capgo/cli channel add stablenpx @capgo/cli channel set stable --disable-auto-update major此配置意味着:
- App 版本为 1.2.3 的用户将收到最高至 1.9.9
- 用户将 不会 收到版本 2.0.0 自动
- 防止破坏性变更影响旧版 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 updatesnpx @capgo/cli channel set stable --disable-auto-update none策略 3:原生版本约束
章节标题:“策略 3:Native 版本约束”为每个 bundle 指定最低 native 应用版本 (min_update_version),以便 Capgo 只将其下发给 native 二进制足够新的设备。
这使用了 channel 元数据 策略 (--disable-auto-update metadata) 以及 --min-update-version 或 --auto-min-update-version 上传时。没有 --native-version CLI 标志。
在 channel 上启用 metadata targeting
章节标题:“在 channel 上启用 metadata targeting”# one-time: require min_update_version metadata on uploads to this channelnpx @capgo/cli@latest channel set production --disable-auto-update metadata上传时设置最低原生版本
标题为“上传时设置最低原生版本”的部分上传 bundle 时,请指定允许接收该 bundle 的最低原生版本:
# This bundle requires native version 2.0.0 or highernpx @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使用场景
标题为“使用场景”的章节-
需要新的原生插件
终端窗口 # Bundle needs Camera plugin added in v2.0.0npx @capgo/cli@latest bundle upload \--channel production \--min-update-version "2.0.0" -
Native API 的破坏性变更
终端窗口 # Bundle uses new Capacitor 6 APIsnpx @capgo/cli@latest bundle upload \--channel production \--min-update-version "3.0.0" -
渐进式迁移
终端窗口 # one-time: enable metadata gating on betanpx @capgo/cli@latest channel set beta --disable-auto-update metadata# Test bundle only on latest native versionnpx @capgo/cli@latest bundle upload \--channel beta \--min-update-version "2.5.0"
策略 4:防止自动降级
标题为“策略 4:防止自动降级”的章节防止用户收到比当前原生版本更旧的 bundle。
在 Channel 设置中启用
标题为“在渠道设置中启用”的章节在 Capgo dashboard 中:
- 前往 通道 → 选择你的 channel
- 启用 “在 native 下禁用自动降级”
- 保存更改
或者通过 CLI:
npx @capgo/cli@latest channel set production --no-downgrade- 用户设备:Native 版本 1.2.5
- Channel bundle:版本 1.2.3
- 结果:更新被阻止(将会导致版本降级)
适用于以下场景:
- 用户已从应用商店手动安装了更新版本
- 您需要确保用户始终拥有最新的安全补丁
- 您希望防止回归 bug
策略 5:设备级定向
标题为“策略 5:设备级定向”的章节为特定设备或用户组覆盖 channel 分配。
为测试强制指定版本
标题为“强制指定测试版本”的章节import { CapacitorUpdater } from '@capgo/capacitor-updater'
// Force beta testers to use v3 channelasync function assignBetaTesters() { const deviceId = await CapacitorUpdater.getDeviceId()
// Check if user is beta tester if (isBetaTester(userId)) { await CapacitorUpdater.setChannel({ channel: 'v3' }) }}Dashboard 设备覆盖
标题为“Dashboard 设备覆盖”的章节在 Capgo dashboard 中:
- 前往 设备 → 查找设备
- 点击 设置 Channel 或 设置 Version
- 用指定 channel 或 bundle version 覆盖
- 设备将从覆盖后的来源接收更新
完整的 AppFlow 风格工作流
标题为“完整的 AppFlow 风格工作流”的章节以下是结合所有策略的完整示例:
1. 初始设置 (App v1.0.0)
标题为“1. 初始设置 (App v1.0.0)”的章节# Create production channel, then enable metadata min-version gatingnpx @capgo/cli@latest channel add productionnpx @capgo/cli@latest channel set production \ --disable-auto-update metadata \ --no-downgradeconst config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'production', } }};2. 发布破坏性变更 (App v2.0.0)
章节“2. 发布破坏性变更 (App v2.0.0)”# Create v2 channel for new versionnpx @capgo/cli@latest channel add v2npx @capgo/cli@latest channel set v2 \ --disable-auto-update metadata \ --no-downgrade \ --self-assign
# Create git branch for v1 maintenancegit checkout -b v1-maintenancegit push origin v1-maintenance// capacitor.config.ts for v2.0.0const config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'atBackground', defaultChannel: 'v2', // New users get v2 channel } }};3. 向两个版本推送更新
章节“3. 向两个版本推送更新”# Update v1.x users (bug fix)git checkout v1-maintenance# Make changesnpx @capgo/cli@latest bundle upload \ --channel production \ --min-update-version "1.0.0"
# Update v2.x users (new feature)git checkout main# Make changesnpx @capgo/cli@latest bundle upload \ --channel v2 \ --min-update-version "2.0.0"4. 监控版本分布
章节“4. 监控版本分布”使用 Capgo dashboard 跟踪:
- v1 与 v2 的用户数量对比
- 各版本的 Bundle 采用率
- 各版本的错误或崩溃情况
5. 弃用旧版本
标题为“5. 弃用旧版本”的章节当 v1 的使用率降至阈值以下时:
# Stop uploading to production channel# Optional: Delete v1 maintenance branchgit branch -d v1-maintenance
# Move all remaining users to default# (They'll need to update via app store)Channel 优先级
标题为“Channel 优先级”的章节当存在多个 channel 配置时,Capgo 使用以下优先级顺序:
- 设备覆盖 (Dashboard 或 API) - 优先级最高,且在 Device Override UI 中可见
- 本地插件频道 通过
setChannel()- 仅存储在设备上,不会在 Device Override UI 中显示 - defaultChannel 在 capacitor.config.ts 中
- 默认频道 (云端设置) - 优先级最低
最佳实践
标题为“最佳实践”的章节1. 务必为大版本设置 defaultChannel
标题为“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 manually2. 使用语义化版本控制
标题为“2. 使用语义化版本控制”的章节# ✅ Good1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
# ❌ Bad1.0 → 1.1 → 2 → 2.53. 维护独立分支
标题为“3. 维护独立分支”的章节# ✅ Good: Separate branches per major versionmain (v3.x)v2-maintenance (v2.x)v1-maintenance (v1.x)
# ❌ Bad: Single branch for all versions4. 发布前进行测试
标题为“4. 发布前测试”的章节# one-time: create beta and enable metadata gating# (production is set up in the complete workflow above)npx @capgo/cli@latest channel add betanpx @capgo/cli@latest channel set beta --disable-auto-update metadata
# Test on beta channel firstnpx @capgo/cli@latest bundle upload \ --channel beta \ --auto-min-update-version
# Monitor for issues, then promote to productionnpx @capgo/cli@latest bundle upload \ --channel production \ --auto-min-update-version5. 监控版本分布
标题为“5. 监控版本分布”的章节定期检查您的 dashboard:
- 用户是否正在升级到新的 Native 版本?
- 旧版本是否仍有高流量?
- 是否应该弃用旧的 Channel?
与 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 |
| 多版本维护 | 手动管理分支/Channel | 基于 Channel 优先级自动管理 |
| 自托管 | 否 | 是(完全控制) |
| 版本分析 | 基础版 | 详细的按版本指标 |
故障排除
“故障排除”章节用户收不到更新
标题为“用户收不到更新”的章节请检查以下各项:
-
Channel 分配:确认设备在正确的 channel 上
const channel = await CapacitorUpdater.getChannel()console.log('Current channel:', channel) -
版本约束:检查 bundle 是否有原生版本要求
- Dashboard → Bundles → 检查“Native Version”列
-
Semver 设置:确认 channel 的
disable-auto-update设置终端窗口 npx @capgo/cli channel list -
设备覆盖:检查设备是否启用了手动覆盖
- Dashboard → Devices → 搜索设备 → 检查 channel/version
Bundle 下发到了错误的版本
标题为“Bundle 分发到了错误版本”的章节- 检查 defaultChannel:确保 中的 channel 正确
capacitor.config.ts - 检查 Bundle 上传:验证 bundle 已上传到目标 channel
- 检查最低更新版本: 确认
--min-update-version(或--auto-min-update-version) 已设置,且该 channel 使用--disable-auto-update metadata
影响旧版本的 Breaking Changes
标题为“影响旧版本的 Breaking Changes”的章节- 立即修复方案: 将受影响的设备覆盖到安全 bundle
- Dashboard → 设备 → 批量选择 → 设置版本
- 长期修复方案: 创建版本化 channel 并维护独立分支
- 预防措施: 在发布更新前,务必在代表性设备上进行测试
从 Ionic AppFlow 迁移
“从 Ionic AppFlow 迁移”部分如果您正在从 Ionic AppFlow迁移,Capgo 中的版本目标设置非常相似,且灵活性更高:
概念对照
“概念映射”部分| AppFlow 概念 | Capgo 对应项 | 备注 |
|---|---|---|
| 部署通道 | Capgo 通道 | 概念相同,功能更强 |
| 原生版本锁定 | --min-update-version / --auto-min-update-version | 更细粒度的控制 |
| 通道优先级 | 通道优先级(覆盖 → 云端 → 默认) | 优先级更透明 |
| 部署目标 | 通道 + semver 控制 | 提供多种策略 |
| 生产环境频道 | production channel(或任意名称) | 灵活命名 |
| 基于 Git 的部署 | 从分支执行 CLI bundle upload | 相同的工作流 |
| 自动版本匹配 | defaultChannel + 版本约束 | 增强多种策略 |
AppFlow 用户的核心差异
章节标题:“AppFlow 用户的关键差异”- 更多控制:Capgo 提供多种可组合的策略(channels、semver、native version)
- 更好的可见性:Dashboard 显示版本分布和兼容性问题
- API 访问权限:对版本目标进行完全的程序化控制
- 自托管:选择运行自己的更新服务器,使用相同的版本逻辑
迁移步骤
标题为“迁移步骤”的章节- 映射您的 Appflow 频道 到 Capgo 频道(通常 1:1)
- 设置
defaultChannel中的capacitor.config.ts针对每个主版本 - 配置 semver 规则 如果您希望在版本边界处自动拦截
- 上传特定版本的 bundle 使用
--min-update-version(channel 必须使用 metadata 策略) - 监控版本分布 在 Capgo dashboard 中
进阶模式
标题为“高级模式”的章节按版本渐进发布
标题为“按版本渐进发布”的章节// Gradually migrate v1 users to v2async 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' }) }}按版本配置 Feature Flags
标题为“按版本配置 Feature Flags”的章节// Enable features based on native versionasync 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 测试
标题为“跨版本 A/B 测试”的章节// Run A/B tests within same native versionasync 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 针对特定版本的更新分发提供多种策略:
- 基于 Channel 的路由:通过自动版本隔离
defaultChannel - 语义化版本规范:防止跨主版本/次版本/补丁版本边界的更新
- 原生版本约束:要求 bundle 满足最低原生版本
- 自动降级防护:绝不向较新的原生版本下发较旧的 bundle
- 设备级覆盖:用于测试和定向的手动控制
结合这些策略,你可以实现类似 AppFlow 的自动更新分发,同时拥有更高的灵活性和控制力。选择最适合你应用版本管理和部署工作流的方式。
有关具体功能的详细信息:
- 破坏性变更指南 - 详细的 Channel 版本管理策略
- Channel 管理 - 完整的 Channel 配置参考
- 更新行为 - Native 版本延迟与条件
从版本定向继续
标题为“从版本定向继续”的章节如果你正在使用 版本定向 要规划 Channel 路由和分阶段发布,请将其与 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, 通道 有关 Channels 的实现细节, Beta 测试解决方案 适用于 Beta Testing Solution 产品工作流的,以及 版本定向解决方案 适用于 Version Targeting Solution 产品工作流的。