破坏性变更

本文档介绍了如何通过版本化 Channel 来处理 App 中的 breaking changes。这种方法允许您维护不同版本的 App，同时确保用户收到兼容的更新。

示例场景

假设您当前的情况如下：

• App 版本 1.2.3 (旧版本) - 使用 production channel
• App 版本 2.0.0 (包含 breaking changes 的新版本) - 使用 v2 channel
• Live update 1.2.4 (与 1.2.3 兼容)
• Live update 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'

提示

此方案的优势：

• 始终掌握控制权 决定哪些用户能收到更新
• 无需动态切换 Channel 你的应用 code 中不再需要
• 清晰的分离 不同应用版本之间
• 灵活性 以便向任何特定的版本组推送更新

1. 为新版本创建 Channel

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

2. 更新 2.0.0 版本的 Capacitor 配置

在为 App Store 构建 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 channel。对于未来的大版本，请务必设置特定的 channel，例如 v3, v4，等等。

3. 管理独立的 Code 分支

创建独立的 git 分支，以保持不同 App 版本之间的兼容性：

# 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

重要： 切勿向旧版 App 推送 JavaScript bundle，这些 App 期望使用其并不具备的原生 code/API。请始终从合适的分支构建更新：

• v1-maintenance 分支：用于 1.x 版本 App 的更新（production channel）
• main 分支：用于 2.x 版本 App 的更新（v2 channel）

4. 将 Bundle 上传到对应 Channel

# 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 版本并发布到 App Store。所有下载此版本的用户（无论是新用户还是升级的现有用户）都会自动使用 v2 channel，因为该配置已包含在 app bundle 中。

注意

无需更改 code！ 自 defaultChannel: 'v2' 已随应用商店版本一起打包，所有下载 2.0.0 版本的用户都会自动使用正确的 channel。

扩展到未来版本

当你发布包含更多 breaking changes 的 3.0.0 版本时：

# Create channel for version 3.x
npx @capgo/cli channel add 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 channel：

npx @capgo/cli channel delete v2

3. 删除 v1-maintenance 分支：

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

提示

这种方式可确保用户仅收到与其 App 版本兼容的更新

在部署之前，请务必在每个 channel 中对更新进行彻底测试

注意

即使部分用户仍保留了 channel override，你也可以安全地删除 Capgo 中的 v2 channel。他们会自动接收来自 production channel 的更新。

维护 Version 1.x 更新

若要发送与 version 1.x 兼容的更新：

1. 切换到 v1-maintenance 分支：

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. 构建并上传至生产环境 channel：

npx @capgo/cli bundle upload --channel production

提示

确保 v1-maintenance 分支包含与 1.x 版本兼容的 bug 修复，但切勿将 main 分支中的 breaking changes 合并进来

继续阅读 Breaking Changes

如果你正在使用 破坏性变更 要规划 Channel 路由和分阶段发布，请将其与 通道 有关 Channels 的实现细节， 通道 有关 Channels 的实现细节， 通道 有关 Channels 的实现细节， Beta 测试解决方案 适用于 Beta Testing Solution 产品工作流的，以及 版本定向解决方案 适用于 Version Targeting Solution 产品工作流的。