Breaking Changes

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

示例场景

假设您有：

• 应用程序版本 1.2.3（旧版本）- 使用生产通道
• 应用程序版本 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'

提示

此方法的好处：

• 始终有控制权 决定哪些用户接收更新
• 不需要在应用中切换动态通道 code
• 清晰的分离 不同应用版本之间
• Flexibility to push updates to any specific version group

1. Create Channel for New Version

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

2. Update Capacitor Config for Version 2.0.0

Update your Capacitor config before building version 2.0.0 for the app store:

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

关键： Never push JavaScript bundles to older apps that expect native code/APIs they don’t have。始终从适当的分支构建更新：

• 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

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

注意

无需任何code更改! 由于它与应用商店版本捆绑在一起，因此所有下载版本 2.0.0 的用户都会自动使用正确的通道。 defaultChannel: 'v2' 到未来的版本进行扩展

标题：到未来的版本进行扩展

标题：当您发布具有更多破坏性更改的版本 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 channel → 版本 1.x 用户
• v2 channel → 版本 2.x 用户
• v3 channel → 版本 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

如果您正在使用 Breaking Changes 来规划通道路由和分阶段发布，连接它与 Channels 查看Channels的实现细节 Channels Channels的实现细节 Channels Channels的实现细节 帮代测试端合突 Beta Testing Solution的产品工作流程 端合突代测试端合突 Version Targeting Solution的产品工作流程