跳转至正文
PR 预览

在真机上审查每个 Pull Request

您的 CI 会把每个 Pull Request 的 web build 上传到独立的 Capgo channel。评审人员扫描 QR code 或在 App 里切换 channel,就能在自己的设备上试用;PR 关闭后,该 channel 会自动删除。native code 的改动仍需重新 build。

  • 每个 Pull Request 对应一个 Channel
  • QR code 预览
  • PR 关闭时自动清理

问题

Web 变更不应需要新的二进制文件才能审查

使用商店测试构建来审查 PR

  1. 开发者打开 PR

    变更已准备好审查,但还没有人能在手机上尝试。

  2. 构建、签名并上传

    有人为该分支构建原生二进制文件,签名,上传到 TestFlight 或 Play 测试轨道,然后等待处理。

  3. 邀请并安装

    审查者需要被添加为测试者,并安装该特定构建。

  4. 每次修复都重复

    每个改变 code 的审查评论都意味着另一次构建、另一次上传和另一次安装。

即使只有 JavaScript 变更,每轮审查都要等待原生构建。

这对团队的成本

每次 build

等待商店处理

你上传到 TestFlight 或 Play 测试轨道的每个 build,都需要先经过处理,测试人员才能安装。每个 build 都是如此。

每个 PR

都需要单独的 Native Build 才能测试

如果没有 Live Updates,即使只是 Web 端的改动,审核人员也得等有人完成构建、签名并上传新的二进制文件后,才能测试该分支。

反馈滞后

审核时作者已转向其他任务

当审核要等 build 时,反馈会更晚到达,作者可能已在处理其他任务,分支也会逐渐偏离 main。

工作原理

团队如何使用 Capgo 预览 Pull Request

四个 CI 步骤:一次性设置作用域密钥、每次 push 时上传、分享预览、关闭时清理。以下所有命令均来自 Capgo 文档。

  1. 创建 App Preview 密钥并启用预览

    管理员为 CI 创建一个 App Preview API 密钥。它可以创建预览 channel 并上传 bundle,但无法更改默认 channel 或生产 channel。每个 App 只需开启一次预览。

    # once, run by an admin (not the preview key)
    npx @capgo/cli@latest app set com.example.app --preview
    App Preview API 密钥
  2. 将 PR 构建上传到独立 channel

    每次 push 时,CI 会构建 web 应用并以唯一的 bundle 版本上传。如果 pr-<number> channel 不存在,bundle upload --channel 会创建该 channel 并把 bundle 关联上去。

    npx @capgo/cli@latest bundle upload com.example.app \
      --apikey "$CAPGO_PREVIEW_KEY" \
      --path ./dist \
      --channel "pr-$PR_NUMBER" \
      --bundle "1.2.3-pr.$PR_NUMBER.$GITHUB_RUN_NUMBER"
    channels 文档中的 PR 预览
  3. 把预览发布到 PR 上

    get-qr 会为该 channel 打印 QR code,加上 --url 则输出预览 URL,方便 CI 把它们加到 PR 评论里。

    npx @capgo/cli@latest get-qr com.example.app \
      --channel "pr-$PR_NUMBER" \
      --apikey "$CAPGO_PREVIEW_KEY" \
      --url
    get-qr 参考
  4. 在 PR 关闭时删除 channel

    在 pull request closed 事件中运行。使用 App Preview 密钥时,它只会删除该密钥创建的 channel 和关联的 bundle。

    npx @capgo/cli@latest channel delete \
      "pr-$PR_NUMBER" com.example.app \
      --apikey "$CAPGO_PREVIEW_KEY" \
      --delete-bundle \
      --success-if-not-found
    channel CLI 参考

评审人员切换到 PR channel 的其他方式

两者都需要一个允许自行分配的 channel。App Preview key 无法设置这一点,因此使用该 key 时,请分享 QR preview,或在控制台中设置 device override。

摇一摇菜单

在内部构建中开启摇一摇菜单。测试人员摇晃设备即可打开 Capgo 的测试菜单,摇一摇频道选择器则让他们选择频道。

// capacitor.config.ts (internal builds)
CapacitorUpdater: {
  shakeMenu: true,
}

应用内切换器

在开发者设置页面添加一个频道字段,并用 PR 频道名称调用 setChannel()。

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

await CapacitorUpdater.setChannel({
  channel: 'pr-123',
  triggerAutoUpdate: true,
})
setChannel() 参考

谁在使用 PR 预览

任何评审 Pull Request 的人都能在手机上查看,而不只是作者。

QA 工程师

  • 在自己的设备上测试 PR 的 Web 构建
  • 无需重新安装 App 即可在 PR 频道间切换
  • 频道名称与 PR 编号一致,这样你就知道正在运行哪个 code

项目经理

  • 在代码合并前先在手机上体验新功能
  • 扫描 PR 上发布的 QR code
  • 直接在 PR 上留下反馈

开发者

  • 在 PR 合并前获取真机反馈
  • 每次 push 都会更新 PR 频道
  • 仅涉及 JavaScript 的变更无需 Native Build

商店测试构建 vs Capgo PR 频道

  • 把 PR 装到手机上

    TestFlight / Play 测试
    Native Build、签名和商店审核
    Capgo PR 频道
    Web build 和 bundle 上传都走 CI
  • 在不同 PR 间切换

    TestFlight / Play 测试
    安装另一个 build
    Capgo PR 频道
    扫描另一个 QR code 或切换 channel
  • 审核人员设置

    TestFlight / Play 测试
    邀请测试人员,然后安装每个 build
    Capgo PR 频道
    仅需安装一次 App
  • Native code 和插件变更

    TestFlight / Play 测试
    是
    Capgo PR 频道
    不,需要 Native Build

使用 Capacitor 构建的应用

产品应用需要可评审的移动端变更

学习、活动及社区类应用可以同时评审 onboarding、练习、直播课和订阅变更。PR previews 让产品、QA 和支持团队在合并前检查移动端可用的 build。

StudySmarter - 学校与大学应用图标 教育

StudySmarter - 学校与大学

教育类应用,课时、课程和订阅的变更需经利益相关者审核。

Google Play 安装量
650万
应用商店评分
4.8
Poll Everywhere 应用图标 商务

Poll Everywhere

实时互动应用,活动流程应在合并前完成测试。

Google Play 安装量
110 万
应用商店评分
3.2
lichess • Free Online Chess 应用图标 棋盘

lichess • 免费在线象棋

社区应用,其锦标赛和分析界面可受益于设备预览。

Google Play 安装量
1130万
应用商店评分
4.3

客户证言

使用 Capgo 交付的团队怎么说

5.0/5 开发者团队评分 9,400+ 团队 查看评价

Nate van Jole

CTO, 私有

“配置不到一天就完成了。基于 Channel 的发布让我能先在自己的设备上测试,再推给生产用户。”

Michael Haberler 的肖像

Michael Haberler

nethead emeritors

“这个 updater 插件做得太棒了。它在我这儿运行完美,live updates 对快速测试迭代是极大的加速。”

no-tone @ Webincode

开发者,Webincode

&ldquo;能把特定 Device ID 加入指定分组,并只向这些分组推送更改,太救命了。&rdquo;

常见问题

团队关于 PR preview 的常见问题

为配置 CI 的人和做评审的人提供直截了当的答案。

评审人员需要为每个 PR 都做一次新的 build 吗?

如果 PR 只改动了 Web 层,就不需要。评审人员只需安装一次 app,每个 PR 的 JavaScript、HTML、CSS 和 assets 都会进入各自的 channel。如果 PR 新增了 plugin 或改动了原生 code,就需要原生 build。在 CI 中运行 build needed 即可检测出这种情况。

哪些场景需要 Native Build

CI key 会影响我们的生产 channel 吗?

使用 App Preview API key 时不会。它可以创建 preview channel、上传 bundle,并且只能删除自己创建的 channel 和 bundle。它无法更改默认或主 channel。在 GitHub Actions 中,请在 pull_request 而非 pull_request_target 上运行 job,并限制为只处理来自同一仓库的 PR。

App Preview API 密钥

评审人员如何打开预览?

管理员用 app set --preview 启用一次预览即可。之后 get-qr 会为该 PR channel 输出一个 QR code,--url 会输出 Web 预览 URL 和 deep link。把它们发到 PR 评论里就行。

get-qr 参考

旧的 PR channel 和 bundle 会怎么处理?

在 pull request closed 事件中添加一个 job,运行带 --delete-bundle 和 --success-if-not-found 的 channel delete。使用 App Preview key 时,这会删除该 channel 及其关联的 bundle。更早 push 产生的 bundle 可以用有 delete 权限的 key 通过 bundle cleanup 清理掉。

channel CLI 参考

支持 GitLab、Bitbucket 或 Azure DevOps 吗?

可以。步骤就是 Capgo CLI 命令,因此能在任何 CI 中运行。文档里有 GitHub Actions、GitLab CI、Bitbucket Pipelines 和 Azure DevOps 的集成指南。

CI/CD 集成

在手机上预览你的下一个 Pull Request

在免费试用期间,把 upload、QR 和 cleanup 步骤加到你的 CI 里,并在自己的 App 上试试。

14 天免费试用,无需信用卡。原生变更仍需重新 build。