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' 应用商店版本中已包含

所有下载版本 2.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 频道 → 版本 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 频道 频道 频道 频道 频道 Beta 测试解决方案 为 Beta 测试解决方案中的产品工作流程, 和 版本目标解决方案 为版本目标解决方案中的产品工作流程.