将每个Pull Request转换为可安装的预览

每个移动开发团队都曾经感受到的痛苦：一个功能已经准备好进行审查，但将其传递给利益相关者的手中意味着要穿越 TestFlight 或 Google Play beta 审核迷宫。应该花费几分钟的时间却变成了等待、安装和管理 beta 版本的几个小时。

如果您的生产应用程序可以直接从任何 Pull Request 中拉取最新的更改，并将其直接应用到设备上，而无需重新安装或等待应用商店延迟?

这就是 PR 预览 使之成为可能。当开发人员打开一个 Pull Request 时，一个 GitHub 动作创建一个专用更新通道并发布更改。任何安装了该应用程序的人都可以切换到该通道，测试该功能，并切换回原来的应用程序 - 甚至不用离开他们已经拥有的应用程序。

测试 Flight 问题

测试移动功能的传统工作流程大致如下:

1. 开发人员打开 PR - Code 已经准备好进行审查
2. 等待 TestFlight - 15-30 分钟的处理时间
3. 找到并安装 - 测试者寻找合适的构建
4. 测试和重复 - 每次变更都意味着等待

这会造成瓶颈。 QA 等待构建而被阻塞。产品经理无法快速验证功能。开发者在等待反馈时会失去上下文。行业估计每个 PR 的生产力损失约为 340 美元。

PR 预览的工作原理

PR 预览使用 Capgo 的频道系统来创建每个 PR 的更新流。以下是流程:

1. PR 打开或更新 - GitHub 动作触发
2. 打包上传 - 你的 JS/CSS 变更会上传到一个 PR 专属的频道
3. Comment posted -
4. Instant testing -

No new app installations. No TestFlight delays. The same production app can pull from different update channels.

Setting Up PR Previews

Before you can implement PR previews, your project needs to be configured with Capgo Live Updates. Follow the Capgo quickstart guide if you haven’t already.

GitHub Actions Workflow

Create .github/workflows/pr-preview.yml:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install Dependencies
        run: bun install

      - name: Build
        run: bun run build

      # Create a channel named after your PR (may already exist on synchronize)
      - name: Create PR Channel
        id: create_channel
        continue-on-error: true
        run: bunx @capgo/cli@latest channel add pr-${{ github.event.pull_request.number }} --self-assign
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Upload the build to that channel
      - name: Upload to Capgo
        run: bunx @capgo/cli@latest bundle upload --channel pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Post a comment with testing instructions (only on PR open)
      - name: Comment on PR
        if: github.event.action == 'opened'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: ${{ github.event.pull_request.number }},
              body: '📱 **Test this PR on device:**\n\nOpen your app and switch to channel: `pr-${{ github.event.pull_request.number }}`\n\nUse the shake menu or call `setChannel()` from your app.'
            })

The key is the --self-assign 在创建频道时设置标志。这使测试人员可以在应用程序内使用 setChannel() API.

设置Capgo令牌

1. 前往您的 Capgo控制台
2. 导航到设置 > API密钥
3. 生成一个新的密钥 all 权限
4. 将其添加为 CAPGO_TOKEN 在您的GitHub仓库密钥中

测试人员如何切换频道

测试人员有两种方式可以切换到PR频道:

选项 1：摇动菜单（最简单）

在您的Capacitor配置中启用摇动菜单和渠道选择器：

// capacitor.config.ts
const config: CapacitorConfig = {
  // ... your other config
  plugins: {
    CapacitorUpdater: {
      shakeMenu: true,
      allowShakeChannelSelector: true
    }
  }
};

测试人员摇动他们的设备以打开调试菜单，菜单中显示可用的渠道列表，带有搜索栏。他们找到他们的PR渠道（例如，）、点击选择它，应用程序自动下载并应用更新。当测试完成后，他们再次摇动并切换回生产环境。 pr-123摇动菜单自动处理整个流程：

通过__CAPGO_KEEP_0__获取所有可自行 assignments 的渠道

1. 显示渠道列表并带有搜索功能以找到特定的PR listChannels()
2. 下载更新后选择渠道
3. 提示重新加载并显示“立即重新加载”/“稍后”选项
4. 选项 2：自定义渠道选择器 UI

在您的应用程序中构建一个渠道 switcher，列出可用的PR渠道并让测试人员选择一个。这使用了两个关键API：

- 获取所有启用自行 assignments 的渠道

• listChannels() - 获取所有可自行 assignments 的渠道
• setChannel() - 将设备切换到所选频道

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Get all available channels (including PR channels)
async function getAvailableChannels() {
  const { channels } = await CapacitorUpdater.listChannels();

  // Filter to show only PR channels
  const prChannels = channels.filter(c => c.name.startsWith('pr-'));

  return prChannels;
}

// Switch to a specific PR channel
async function switchToChannel(channelName: string) {
  await CapacitorUpdater.setChannel({
    channel: channelName,
    triggerAutoUpdate: true  // Immediately check for updates
  });
}

// Return to production
async function switchBackToProduction() {
  await CapacitorUpdater.unsetChannel({});
}

// Get current channel
async function getCurrentChannel() {
  const { channel } = await CapacitorUpdater.getChannel();
  return channel;
}

使用这些基本组件，您可以创建一个简单的UI：

// Example: List PR channels and let user select
const channels = await getAvailableChannels();
const current = await getCurrentChannel();

// Display channels in your UI
channels.forEach(channel => {
  console.log(`${channel.name} ${channel.name === current ? '(current)' : ''}`);
});

// When user selects a channel
await switchToChannel('pr-123');

要查看完整的React组件示例，请参阅 我们的频道浏览文章.

清理PR频道

当PR被合并或关闭时，您需要清理频道。添加另一个工作流程：

name: Cleanup PR Preview
on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Delete PR Channel
        run: bunx @capgo/cli@latest channel delete pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

这会在PR关闭时删除频道，使您的频道列表保持干净。

版本兼容性

PR预览仅在JavaScript包与安装的原生版本兼容时才有效。如果您的PR包含原生code更改（新Capacitor插件，iOS/Android修改），测试人员将需要一个新的原生构建。

Capgo会自动检查版本兼容性。如果一个PR的包目标的是不同的原生版本，而不是安装的版本，更新将不会被应用。这会防止由于不兼容code而引起的崩溃。

对于需要原生更改的PR，您需要分发一个新的TestFlight/Play Store构建。PR预览对于JavaScript、CSS和资产更改最有效，这些更改不涉及原生code。

谁从PR预览中受益

测试工程师

• PR 打开时立即测试特性
• 在不重新安装的情况下切换多个 PR
• 在真实设备上验证修复和回归
• 不再等待 TestFlight 处理

产品经理

• 在合并之前审查特性
• 直接在 PR 上给出反馈
• 验证实现与要求相符
• 减少审查周期

开发者

• 更快速地获得对变化的反馈
• 向投资者展示实时演示
• 与特定用户一起调试问题
• 减少管理beta版本的时间

比较：传统版vs PR预览

最佳实践

1. 明确命名频道: 使用 pr-{number} 为易于识别而使用的约定
2. 自动清理: PR 关闭时始终删除通道
3. 限制访问: 只在 debug/staging 构建中启用抖动菜单
4. 文档过程: 将测试指南添加到您的 PR 模板
5. 优雅地处理失败: 在发表评论之前检查通道创建是否成功

何时不使用 PR 预览

PR 预览适用于 JavaScript/CSS 变更。如果您的 PR 包含:

• 新Capacitor插件
• iOS原生code变更
• Android原生code变更
• 影响原生构建的依赖更新

您需要传统的TestFlight/Play Store分发来实现这些变更。

结合Channel Surfing

PR预览最佳与 频道浏览。您的应用程序可以具有：

• production - 对所有用户的稳定版本
• beta - 对选入用户的早期访问
• pr-123 - 特定PR的功能预览

测试者可以在生产环境中切换到任何PR频道，测试功能，然后切换回原来的应用程序 - 所有这些操作都可以在同一个安装的应用程序中完成。

资源

• Capgo 实时更新文档
• 频道文档
• 频道浏览指南
• CLI 命令参考
• PR预览解决方案页面

结论

PR预览将改变您的团队如何审阅和测试移动功能。您不再需要等待TestFlight处理并管理多个beta版本，测试者可以在几秒钟内切换到任何PR频道，使用他们已经安装的应用程序。

设置很简单 - 只需要一个GitHub Actions工作流文件 - 且收益会在您的团队中积累。QA不会被阻塞，产品经理可以更快地审阅，开发人员可以更快地获得反馈。

首先，将工作流添加到一个仓库中，看到它如何改变您的审阅流程。

继续从 Turn Every Pull Request Into an Installable Preview

If you are using 将每个 Pull Request 转换为可安装的预览 用于规划频道路由和阶段性发布，连接它与 频道 用于 Channels 的实现细节 频道 用于 Channels 的实现细节 频道 用于 Channels 的实现细节 Beta 测试解决方案 用于 Beta 测试解决方案中的产品工作流程， 版本目标解决方案 为产品工作流程在版本目标解决方案中。