自动选择 Live Update 或原生构建
复制一个包含安装步骤和本插件的完整Markdown指南的配置提示
大多数 Capacitor 发布都是 JavaScript-only 的，应该以 live update。有些变更触及本机 code，需要从 code 构建 Capgo 构建. This guide shows how to make GitHub Actions, GitLab CI, or any other CI/CD platform pick the correct path on every push — without a human deciding.
Page/area: Capgo solutions marketing page. Role: Short UI label or navigation item. Seen in: page solutions/white-label.astro. Preserve Capgo product/brand and developer terms exactly. Message key `solutions_white_label_visual_cell3_value` (Solutions White Label Visual Cell3 Value).
。本指南展示如何让 __CAPGO_KEEP_0__ Actions、GitLab CI 或任何其他 CI/CD 平台在每次推送时选择正确的路径 —— 无需人类决定。Capgo已经知道哪个路径是安全的。完成您的网页构建（并在上传或请求本机构建之前），运行：
npx @capgo/cli@latest bundle releaseType com.example.app --channel production# → OTA ship with bundle upload# → native ship with Capgo BuildOTA 表示本地包与已在渠道上发布的包匹配。 native 表示插件、Capacitor版本或其他本地依赖发生了变化——仅通过OTA包无法安全地更新设备。
releaseType 比较 本地包元数据 (Capacitor/Cordova插件和版本)。它不会 查看 、或 ios/, android/, or capacitor.config.*进行依赖兼容性检查——以下示例会同时进行两者。 releaseType 参见
本地兼容性 means the native packages match what is already live on the channel. 了解完整的规则和手册。 bundle compatibility 表格。
前提条件
标题：前提条件- Capgo应用程序已注册并且有一个Capgo __CAPGO_KEEP_1__密钥 Capgo API 密钥 Live Updates上传正在工作（
CAPGO_TOKEN - Live Updates 上传成功
bundle upload） — 见 CI/CD 集成 - Capgo 在 CI 中配置建置凭据，如果您期望原生作业 — 见 GitHub 动作 或 原生作业
- 或
production) - 凭据
metadata一个已存在且与生产匹配的频道（例如--auto-min-update-version频道在
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadataCI/CD管道应该如何工作
How the Pipeline Should Workflowchart TD A[Push / merge] --> B[Install + web build] B --> C["bundle releaseType"] C -->|OTA| D["bundle upload"] C -->|native| E["build request iOS + Android"] E --> F[Store / TestFlight / Play]
- 按照正常的方式构建 Web 资产。
- 如果提交涉及
ios/,android/或capacitor.config.*强制使用原生路径。 - 否则请Capgo
releaseType判断提交是否安全。 - 如果
OTA，上传到--fail-on-incompatible和--auto-min-update-version. - 如果
native，执行Capgo Build，然后上传匹配的捆绑包--auto-min-update-version以便频道的本地元数据得到更新 不 不要--fail-on-incompatible用于该基线上传 — 新的本地包应该有所不同。请参见 Native + OTA 频道工作流 频道级FAQ
GitHub 操作
GitHub Actions一项工作流程，用于控制本地路径，然后根据 releaseType:
name: Capgo Release
on: push: branches: [main]
jobs: decide: runs-on: ubuntu-latest outputs: release_type: ${{ steps.verdict.outputs.type }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v6 with: node-version: '24' cache: 'npm'
- run: npm ci - run: npm run build
- name: Decide OTA vs native id: verdict env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} run: | BEFORE="${{ github.event.before }}" if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')" fi if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "${{ github.sha }}" \ | grep -qE '^(ios/|android/|capacitor\.config\.)'; then TYPE=native echo "Native path/config changed (or no prior commit) — forcing native" else TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]') fi echo "type=$TYPE" >> "$GITHUB_OUTPUT" echo "Capgo release type: $TYPE"
live_update: needs: decide if: needs.decide.outputs.release_type == 'OTA' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v6 with: node-version: '24' cache: 'npm' - run: npm ci - run: npm run build - name: Upload live update env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} run: | npx @capgo/cli@latest bundle upload com.example.app \ --channel production \ --fail-on-incompatible \ --auto-min-update-version
native_build: needs: decide if: needs.decide.outputs.release_type == 'native' runs-on: ubuntu-latest strategy: fail-fast: false matrix: platform: [ios, android] steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v6 with: node-version: '24' cache: 'npm' - run: npm ci - run: npm run build - run: npx cap sync ${{ matrix.platform }} - name: Capgo Build ${{ matrix.platform }} env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} P12_PASSWORD: ${{ secrets.P12_PASSWORD }} CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }} APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }} APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }} APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }} APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }} run: | npx @capgo/cli@latest build request com.example.app \ --platform ${{ matrix.platform }} \ --build-mode release
native_bundle: needs: [decide, native_build] if: needs.decide.outputs.release_type == 'native' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v6 with: node-version: '24' cache: 'npm' - run: npm ci - run: npm run build - name: Upload bundle for new native baseline env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} run: | # Channel must already be on metadata (see Prerequisites above) npx @capgo/cli@latest bundle upload com.example.app \ --channel production \ --auto-min-update-version替换 com.example.app 并将签名密钥按照 GitHub GitHub 的动作 Capgo 构建.
以便后续的检查可以看到新原生包。
GitLab CIGitLab评估 rules 当管道创建时，GitLab评估分支中的shell if 内部一个部署作业（或生成一个动态子管道） 如果您需要单独的本机矩阵作业）： .gitlab-ci.yml
image: node:24
stages: - build - deploy
variables: APP_ID: com.example.app CHANNEL: production
build_web: stage: build script: - npm ci - npm run build artifacts: paths: - dist/ - node_modules/ expire_in: 1 hour only: - main
deploy: stage: deploy needs: [build_web] script: - | BEFORE="${CI_COMMIT_BEFORE_SHA:-}" if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')" fi if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "$CI_COMMIT_SHA" \ | grep -qE '^(ios/|android/|capacitor\.config\.)'; then TYPE=native else TYPE=$(npx @capgo/cli@latest bundle releaseType "$APP_ID" --channel "$CHANNEL" | tr -d '[:space:]') fi echo "Capgo release type: $TYPE" if [ "$TYPE" = "OTA" ]; then npx @capgo/cli@latest bundle upload "$APP_ID" \ --channel "$CHANNEL" \ --fail-on-incompatible \ --auto-min-update-version elif [ "$TYPE" = "native" ]; then npx cap sync npx @capgo/cli@latest build request "$APP_ID" --platform ios --build-mode release npx @capgo/cli@latest build request "$APP_ID" --platform android --build-mode release npx @capgo/cli@latest bundle upload "$APP_ID" \ --channel "$CHANNEL" \ --auto-min-update-version else echo "Unexpected release type: $TYPE" >&2 exit 1 fi only: - mainStore CAPGO_TOKEN 并且 Capgo 将构建签名变量作为掩码/保护的CI/CD变量。
Section titled “Other CI Platforms”
其他CI平台无论在哪里，相同的三个步骤都有效：
| 步骤 | 命令 |
|---|---|
| 判决 | npx @capgo/cli@latest bundle releaseType APP_ID --channel production |
| OTA路径 | npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version |
| 原生路径 | npx @capgo/cli@latest build request APP_ID --platform ios (或 android) --build-mode release |
将 shell 退出/标准输出映射到您的平台的条件语句（或保留一个 shell ifGitLab（如上所示）
- Azure Pipelines —从脚本步骤设置一个输出变量，然后使用
condition: eq(variables['releaseType'], 'OTA') - Bitbucket Pipelines — 写
RELEASE_TYPE=…到$BITBUCKET_PIPELINES_VARIABLES_PATH在产品页面中，Live Updatesoutput-variables，在condition: state: RELEASE_TYPE == "OTA"，并在后续步骤中分支condition) - (仅文件存档无法驱动 —
whenCircleCIif在配置编译时间评估，因此使用一个运行时shellwhen - Jenkins Jenkins
when { environment name: 'RELEASE_TYPE', value: 'OTA' }
— 将 stdout 捕获到一个环境变量中并使用
路径过滤（可选加速）路径过滤器是一种成本优化，而不是Capgo检查的替代品。更倾向于排除仅用于文档的路径，而不是维护一个脆弱的白名单——web构建通常还依赖于 vite.config.*, tsconfig*.json,以及框架配置文件:
on: push: branches: [main] paths-ignore: - '**.md' - 'docs/**' - '.github/**'如果您使用白名单代替，包括web和native构建读取的所有输入，而不仅仅是 src/ 和 package.json.
native判决后
native判决后当CI选择native时:
- Capgo构建生成签名的二进制文件并可以提交到TestFlight/Play（请参见 配置).
- 上传匹配的JS包裹
--auto-min-update-version(元数据策略)以便通道记录新的native包裹——否则下一个仅JS提交仍然返回native. - 用户安装新二进制文件后，后续仅包含 JavaScript 的提交将恢复到
OTA再次。
相关指南
标题：相关指南
原生兼容性
为什么 Capgo 返回 OTA vs 原生并且如何阻止坏的上传。
原生 + OTA 通道工作流
开发/生产通道和何时放弃 --fail-on-incompatible 以实现有意的原生基线。
GitHub 动作（Capgo 构建）
签名密钥和完整的原生构建工作流。
从 CI UI 触发构建
从 GitHub、GitLab 或 Bitbucket 运行一个原生构建。
通过 Webhook 触发构建
从管理控制台或任何 HTTP 客户端触发 Capgo 构建
