断点变化

本文档解释了如何在您的应用程序中处理破坏性更改的方法，使用版本化通道。这一方法允许您维护应用程序的不同版本，同时确保用户接收兼容的更新。

示例场景

假设您有：

• 应用程序版本 1.2.3（旧版本）- 使用生产通道
• App 版本 2.0.0 (新版本，包含重大更改) - 使用 v2 通道
• 实时更新 1.2.4 (兼容 1.2.3)
• 实时更新 2.0.1 (兼容 2.0.0)

策略：总是使用 defaultChannel 为主要版本

推荐方法： 为每个主要版本设置一个 defaultChannel 。这样您就可以始终将更新推送到特定用户组，而不依赖动态通道分配。

// Version 1.x releases
defaultChannel: 'v1'

// Version 2.x releases
defaultChannel: 'v2'

// Version 3.x releases (future)
defaultChannel: 'v3'

提示

此方法的好处：

• 始终保持控制权 over which users receive updates
• 不需要在应用中进行动态频道切换 needed in your app code
• 清晰的分离 between different app versions
• 灵活性 to push updates to any specific version group

1. 为新版本创建频道

# Create channel for version 2.x
npx @capgo/cli channel create v2

2. 更新 Capacitor 配置为版本 2.0.0

在发布应用商店版本 2.0.0之前，请更新您的 Capacitor 配置：

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      // ... other options
      defaultChannel: 'v2' // All 2.0.0 users will use v2 channel
    }
  }
};

export default config;

注意

对于版本 1.x： 如果您没有设置一个 defaultChannel 最初，版本 1.x 用户位于 production 频道。对于未来的主要版本，请始终设置一个特定的频道，如 v3, v4等等。

3. 独立管理Code分支

为保持应用程序版本之间的兼容性，创建独立的git分支：

# Create and maintain a branch for version 1.x updates
git checkout -b v1-maintenance
git push origin v1-maintenance

# Your main branch continues with version 2.x development
git checkout main

重要提示： 永远不要将JavaScript包推送到期望native code/APIs但实际上没有的旧应用程序。始终从适当的分支构建更新：

• v1-maintenance branch: 对1.x应用程序的更新（生产频道）
• main branch: 对2.x应用程序的更新（v2频道）

4. 将包上传到相应的频道

# For 1.x updates: Build from v1-maintenance branch
git checkout v1-maintenance
# Make your 1.x compatible changes here
npx @capgo/cli bundle upload --channel production

# For 2.x updates: Build from main branch
git checkout main
# Make your 2.x changes here
npx @capgo/cli bundle upload --channel v2

5. 启用自我分配

# Allow apps to self-assign to v2 channel
npx @capgo/cli channel set v2 --self-assign

6. 部署到 App Store

在 App Store 上部署版本 2.0.0。所有下载此版本的用户（新用户或升级的现有用户）都会自动使用 v2 通道，因为它在应用程序包中配置。

注意

No code 需要任何更改! 自从 defaultChannel: 'v2' 已与应用商店版本捆绑，所有下载版本 2.0.0 的用户都会自动使用正确的渠道。

扩展到未来版本

当您发布版本 3.0.0 时，带有更多破坏性更改：

# Create channel for version 3.x
npx @capgo/cli channel create v3

// capacitor.config.ts for version 3.0.0
const config: CapacitorConfig = {
  // ...
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'v3' // Version 3.x users
    }
  }
};

现在您可以推送任何版本的更新：

• production 渠道 → 版本 1.x 用户
• v2 渠道 → 版本 2.x 用户
• v3 channel → Version 3.x 用户

7. 清理（迁移后）

一旦所有用户都迁移到版本 2.x（计时 3-4 个月）：

1. 移除 defaultChannel 从您的 Capacitor 配置中
2. 删除 v2 频道：

npx @capgo/cli channel delete v2

3. 删除 v1-maintenance Branch：

git branch -d v1-maintenance
git push origin --delete v1-maintenance

提示

这项方法确保用户只接收与其应用程序版本兼容的更新

在每个渠道中都要彻底测试更新之前始终进行部署

注意

You can safely delete the v2 channel in Capgo even if some users still have the channel override. They will automatically receive updates from the production channel instead.

维护 1.x 版本更新

要发送与 1.x 版本兼容的更新：

1. 切换到 v1-maintenance branch：

git checkout v1-maintenance

2. 请在本地环境中进行修改并提交：

# Make 1.x compatible changes
git add .
git commit -m "Fix for v1.x"
git push origin v1-maintenance

3. 将应用程序构建并上传到生产环境：

npx @capgo/cli bundle upload --channel production

提示

保持v1-maintenance branch与1.x版本兼容的bug修复同步，绝不从main合并破坏性变更

继续从Breaking Changes

If you are using __CAPGO_KEEP_0__ to plan channel routing and staged rollout, connect it with __CAPGO_KEEP_1__ for the implementation detail in __CAPGO_KEEP_1__, __CAPGO_KEEP_1__ for the implementation detail in __CAPGO_KEEP_1__, __CAPGO_KEEP_1__ for the implementation detail in __CAPGO_KEEP_1__, __CAPGO_KEEP_2__ for the product workflow in __CAPGO_KEEP_2__, and __CAPGO_KEEP_3__ for the product workflow in __CAPGO_KEEP_3__ Breaking Changes 为了计划通道路由和阶段性发布,请连接 Channels 为了实现细节,请参阅 Channels 为了实现细节,请参阅 Channels 为了实现细节,请参阅 Beta Testing Solution 为了产品工作流程,请参阅 Version Targeting Solution 用于产品工作流程的版本目标解决方案。