每个移动开发团队都曾经感受到的痛苦：功能准备就绪，但将其传递给利益相关者意味着要穿越TestFlight或Google Play beta review迷宫。应该花几分钟的时间，但却变成了等待、安装和管理beta版本的几个小时。
如果您的生产应用程序可以从任何Pull Request中拉取最新的更改并直接将其加载到设备上，而无需重新安装或应用商店延迟?
这就是 PR预览 当开发者打开一个拉取请求时，一个 GitHub 动作创建一个专门的更新频道并发布更改。任何安装了该应用的人都可以切换到该频道，测试该功能并切回原来的应用——所有这些都不需要离开他们已经有的应用。
TestFlight 问题
传统的测试移动功能的工作流程大致如下：
- 开发者打开 PR - Code 等待审查
- 等待 TestFlight - 15-30 分钟的处理时间
- 查找并安装 - 测试者搜索正确的构建
- 测试和重复 - 每次更改都意味着等待
这会造成瓶颈。QA 等待构建而被阻塞。产品经理无法快速验证功能。开发者在等待反馈时会失去上下文。行业估计，这种情况每个 PR 的生产力损失约为 340 美元。
PR 预览的工作原理
PR 预览使用 Capgo 的频道系统来创建每个 PR 更新流。以下是流程：
- PR 打开或更新 - GitHub 动作触发
- 上传包 - 您的 JS/CSS 更改将发送到 PR 特有的频道
- 评论发布 - 测试者在 PR 中获得指示
- 即刻测试 - Switch 频道，测试，Switch 回
无需新应用安装。无需 TestFlight 延迟。同一生产应用可以从不同的更新频道拉取。
设置 PR 预览
在您可以实现 PR 预览之前，需要先配置您的项目以使用 Capgo Live Updates。请遵循 Capgo 快速入门指南 如果您还没有。
GitHub Actions 工作流
创建 .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.'
})关键是 --self-assign 标志，当创建频道时使用。这样测试者就可以在应用程序中切换到频道使用 setChannel() API。
设置 Capgo Token
- 前往您的 Capgo 控制台
- 导航到设置 > API 密钥
- 生成一个新的密钥
all__CAPGO_KEEP_0__ - 添加它作为
CAPGO_TOKEN在您的GitHub仓库密钥中
测试人员如何切换频道
测试人员有两种方式切换到PR频道:
选项1：摇动菜单（最简单）
在您的Capacitor配置中启用摇动菜单的频道选择器:
// capacitor.config.ts
const config: CapacitorConfig = {
// ... your other config
plugins: {
CapacitorUpdater: {
shakeMenu: true,
allowShakeChannelSelector: true
}
}
};测试人员摇动他们的设备以打开调试菜单，显示可用的频道列表以及一个搜索栏。他们找到他们的PR频道（例如，"__CAPGO_KEEP_0__"），点击选择它，应用程序自动下载并应用更新。当测试完成时，他们再次摇动以切换回生产环境。 pr-123摇动菜单自动处理整个流程:
通过
- 获取所有可自行分配的频道
listChannels() - 显示包含搜索功能的频道以便找到特定的PR
- 下载选定的更新
- 提示重新加载，提供“立即重新加载”/“稍后”选项
选项2：自定义频道选择器UI
在应用中构建一个频道切换器，列出可用的PR频道并让测试者选择一个。这个功能使用以下两个关键API：
listChannels()- 获取所有具有自我赋值功能的频道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 预览中受益
QA 工程师
- 测试特性立即在 PR 打开时
- 在多个 PR 之间切换而无需重新安装
- 在真实设备上验证修复和回归
- 不再等待 TestFlight 处理
产品经理
- 查看功能之前合并
- 直接在 PR 上给出反馈
- 验证实现是否符合要求
- 减少审查周期
开发者
- 更快速地在更改上获得反馈
- 即时演示功能给利益相关者
- 使用特定用户调试问题
- 减少管理 beta 版本的时间
比较：传统版 vs PR 预览
| 方面 | TestFlight/Beta | Capgo PR 预览 |
|---|---|---|
| 构建时间 | 15-30 分钟 | 小于 1 分钟 |
| 切换 PR | 5+ 分钟重新安装 | 10 秒 |
| 设置复杂度 | 应用商店凭据 | 一个工作流文件 |
| 清理 | 手动 | 自动 |
| 原生 code 变更 | 必需 | 可选 (JS 只) |
最佳实践
- 清晰命名频道: 使用
pr-{number}约定以便识别 - 自动清理: 总是删除频道当 PR 关闭
- 限制访问: 只在 debug/staging 构建中启用 shake 菜单
- 记录流程: 将测试指南添加到您的 PR 模板
- 优雅地处理失败: 在发布评论之前检查通道创建是否成功
什么时候不使用 PR 预览
PR 预览适用于 JavaScript/CSS 变更。如果您的 PR 包含:
- 新 Capacitor 插件
- iOS 原生 code 变更
- Android 原生 code 变更
- 影响原生构建的依赖更新
您将需要传统的 TestFlight/Play Store 分发方式来处理这些变更。
与 Channel Surfing 结合使用
PR 预览功能在与 "频道浏览" 结合使用时效果最佳。 频道浏览您的应用程序可以具有：
production- 对所有用户提供稳定的版本beta- 对已同意的用户提供早期访问pr-123- 为特定 PR 提供功能预览
使用生产环境构建的测试者可以切换到任何 PR 频道，测试功能，然后切换回原来的频道 - 所有这些操作都可以在同一个已安装的应用程序中完成。
资源
结论
PR 预览将改变您的团队如何审阅和测试移动功能。您不再需要等待 TestFlight 处理和管理多个 beta 版本，测试人员可以在几秒钟内切换到任何 PR 通道，使用他们已经安装的应用程序。
设置很简单 - 只需要一个 GitHub Actions 工作流文件 - 并且好处会在您的团队中积累。QA 不会被阻塞，产品经理可以更快地审阅，开发人员可以获得更快的反馈。
开始通过将工作流添加到一个存储库中来尝试它，见看它如何改变您的审阅流程。
