11. Breaking Changes

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

示例场景

让我们假设你有：

• App 版本 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'

提示

这种方法的好处:

• 始终控制 哪些用户接收更新
• 不需要在应用中切换动态频道 needed in your app code
• 不同应用版本之间 灵活性
• 推送任何特定版本组的更新 1. 为新版本创建频道

__CAPGO_KEEP_0__

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

2. 为版本 2.0.0 更新 Capacitor 配置

在为应用商店构建版本 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包推送到期望的本机code/APIs但没有的旧应用程序。始终从适当的分支构建更新：

• v1-maintenance branch:用于1.x应用程序更新（生产频道）
• 主分支: 对于 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更改! 由于应用商店版本中包含了 defaultChannel: 'v2' 到未来的版本进行扩展

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

终端窗口

# 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 频道 → 版本 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.

您可以安全地删除 v2 渠道中的 __CAPGO_KEEP_0__。他们将自动从生产渠道接收更新。

为了发送与版本 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与bug修复保持同步，兼容版本1.x，但从main中永远不要合并破坏性更改

继续从Breaking Changes

如果您正在使用 Breaking Changes 用于规划通道路由和分阶段发布 Channels Channels Channels Channels Channels Channels Beta 测试解决方案 为 Beta 测试解决方案中的产品工作流程,并且 版本目标解决方案 为版本目标解决方案中的产品工作流程.