CI/CDのCapacitorの一般的な落とし穴と修正

Most Capacitor CI/CD failures come from the same short list: iOS code signing, missing or outdated macOS tooling, a web build that never made it into the native project, reused build numbers, and store requirements that only fail at upload time. Each has a known cause and a fix you can apply once. This guide groups the pitfalls by pipeline stage, with the error you will see, why it happens, and what to change.

設定から始めて、最初に読んでください、 Setting up CI/CD for Capacitor apps ステージ1: Web層のビルド

ネイティブアプリが古いWebビルドを含む

症状:

原因: CIは成功したが、アプリはインストールされたが、昨日のUIが表示される。

原因: cap sync コピーするのはその時点のものだけです。パイプラインがウェブビルド前に実行される、またはウェブビルドが異なるフォルダに書き込む場合、ネイティブプロジェクトは古いファイルを取得します。 webDir 対処法: cap sync 常にこの順序でステップを実行し、出力フォルダが空の場合に失敗するようにします。 webDir フォルダが capacitor.config.tsと一致していることを確認します（Viteの場合、

] ）

bun install --frozen-lockfile
bun run build
test -f dist/index.html || { echo "web build missing"; exit 1; }
bunx cap sync

です。 webDir です。dist です。 www AngularとIonicのための build 一部のReact設定のための

エラー:開発サーバーのURLが設定ファイルに残っている

症状: リリースビルドでは白い画面が表示されるか、またはロードしようとする http://192.168.x.x:5173.

原因: server.url in capacitor.config.ts 解決策:

Fix: エラー:環境変数が間違ったタイミングで設定されている server.urlCI/CDのためのCapacitorの共通の落とし穴

import type { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  ...(process.env.LIVE_RELOAD_URL && {
    server: { url: process.env.LIVE_RELOAD_URL, cleartext: true },
  }),
}

export default config

CI/CDのためのCapacitorの共通の落とし穴

症状： APIのステージングアプリが生産アプリと通信している。

原因： ビルド時、Vite、webpack、Angularはインライン環境変数を設定します。実行したときの値は、バイナリに含まれ、同じジョブから作成された__CAPGO_KEEP_0__にも含まれます。 bun run build ran はビンナリ内のものであり、同じジョブから作られた任意の live update にもある。

Fix: 落とし穴： cap sync.

CIのプラグインバージョンが自分のマシンと異なり、ネイティブコンパイルがシンボルが見つからないことによる失敗に遭遇します。

症状： ロックファイルをコミットし、インストールする際に

Fix: __CAPGO_KEEP_0__ bun install --frozen-lockfile （または npm ci） Pin @capacitor/core, @capacitor/ios, @capacitor/android、そして @capacitor/cli 同じバージョンに Fix Capacitor version mismatch errors.

__CAPGO_KEEP_0__ バージョン不一致エラーを修正する

ステージ 2：ネイティブツールチェーン

Symptom: Unsupported class file major version, The engine "node" is incompatible, または Xcode のエラーについての SDK 機能です。

Cause: ホストドーナーイメージが変更され、Capacitor 8 は最低限の条件を満たします。

対策: パイプラインで各バージョンを明示的に固定するのではなく、信頼するのではなく latest:

- uses: actions/setup-node@v6
  with:
    node-version-file: .nvmrc
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: '26'

誤り: Xcode Apple がもう受け付けないようにしているため、ビルド

症状: アップロードが失敗し、未対応のSDKでアプリがビルドされたというメッセージが表示されます。

原因: 2026年4月28日以降、App Store ConnectではXcode 26とiOS 26SDKが必要になります。自宅でMacをホストしている場合や古いランナーのイメージがまだ使用されている場合、Xcode 16がデフォルトで使用されます。

対処法: 選択してください macos-26 AppleのXcode 26要件に関する__CAPGO_KEEP_0__アプリ AppleのXcode 26要件はCapacitorアプリに適用されます。.

症状:

、またはpodが見つかりません。 xcodebuild: error: 'App.xcworkspace' does not exist新しい__CAPGO_KEEP_0__ 8プロジェクトではSwift Package Managerを使用してビルドします。

原因: Capacitor 8のプロジェクトはSwift Package Managerを使用し、ビルドしています。 ios/App/App.xcodeproj古いプロジェクトではCocoaPodsを使用し、ビルド ios/App/App.xcworkspace 後 pod install。古いチュートリアルのコピーされたパイプラインは、ワークスペースを想定しています。

Fix: 使用しているプロジェクトがどれを使用しているかを確認し、正しいファイルをビルドしてください。移行中の場合は、 「CapacitorアプリをSPMに移行する方法」を参照してください。.

落とし穴：AndroidプラグインのビルドがGradleのアップグレード後に破損する

症状: Namespace not specified, package attribute is deprecated、またはプラグインの build.gradle 更新後、エラーが発生します。

Fix: Android Gradle プラグインを固定してください android/build.gradle、ブランチでアップグレードし、プラグインを先にアップデートしてください。特定のエラーについては AGP 9でCapacitor プラグインビルドエラーを修正する.

ステージ3: Code署名

落とし穴: iOS署名はMacのみで動作します

症状: No signing certificate "iOS Distribution" found, No profiles for 'com.example.app' were found、または errSecInternalComponent.

原因: Macのキーチェーンには証明書とXcodeがプロファイルをダウンロードするためのものがあります。CIランナーにはそれがありません、そしてそのキーチェーンは非対話型セッションでロックされています。

修正: 証明書を一時的にロックされていないキーチェーンにインポートし、Xcode 16以降がプロファイルを探す場所にインストールしてください:

security create-keychain -p "$KEYCHAIN_PASSWORD" ci.keychain
security set-keychain-settings -lut 21600 ci.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" ci.keychain
security import dist.p12 -k ci.keychain -P "$P12_PASSWORD" -T /usr/bin/codesign
security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" ci.keychain
security list-keychains -d user -s ci.keychain login.keychain

PROFILES="$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles"
mkdir -p "$PROFILES"
cp app.mobileprovision "$PROFILES/"

ID名 Apple Distribution、ではなく、レガシーの iOS Distribution. fastlaneの setup_ci plus match automates this. Capgo Build takes the certificate and profile as environment variables and does the keychain work on its own machines, so the Linux job never touches security.

__CAPGO_KEEP_0__

Symptom: Pitfall: 有効期限切れまたは無効化された証明書

症状: 1年間動作していたパイプラインが夜中に失敗する

原因: Appleの配布用証明書とプロビジョニングプロファイルは1年後に有効期限切れになる。Xcodeで新しい証明書を作成するチームメンバーも、CIで使用しているプロファイルを無効化できる bunx @capgo/cli@latest build prescan --platform ios 対策:

チームカレンダーに有効期限を記載し、CI用に共有する配布用証明書を1つだけ持つ、ビルド前にチェックすること

症状： fastlaneが6桁のcodeを待ってハングアップします。

対策： App Store ConnectのAPIキーを使用してください。.p8落とし穴：

base64シークレットがデコードされない

症状： MAC verification failed, invalid keystore format、または base64: invalid input.

原因： base64値をコピーしたときに改行が追加された、または .p12 OpenSSL 3のデフォルトで作成されたがmacOSが読み取れない

対策： 1行でエンコードし、、、を使用します。 -legacy 作成するときは .p12 OpenSSL 3:　

base64 -i dist.p12 | tr -d '\n' > dist.p12.b64
openssl pkcs12 -export -legacy -inkey key.pem -in cert.pem -out dist.p12

落とし穴: Android キーストアが失われる

症状: アップデートに署名することができません。誰もキーストアを持っていないからです。

解決策: Play App Signingの場合、キーストアはアップロードキーであり、Play Consoleのサポートは新しいキーストアを登録できます。CIシークレットとオフラインバックアップにキーストアを保存してください。1台のノートパソコンにのみ保存しないでください。キーストアは、最初から始める場合に新しいものを作成するAndroid キーストア生成器が作成します。 ステージ 4: Pipelines の設計 落とし穴: プル リクエストごとにネイティブ ビルド

ステージ 4: Pipelines の設計

落とし穴: プル リクエストごとにネイティブ ビルド

症状： PR チェックが遅く、macOS 分数の請求額が大きい。

原因： ホストされた macOS ランナー上で iOS ビルドは、ほとんどの CI プランで最も高価な分数であり、ほとんどのコミットは JavaScript をタッチするのみである。

対策： PR ごとに lint、テスト、ウェブビルドを実行する。リリースタグまたはマージでネイティブビルドを実行する。PR のプレビューでは、ウェブパッケージを __CAPGO_KEEP_0__ チャネルに配信するのではなく、バイナリをビルドするのではなく、記載されているようにする。 mainPR プレビューの場合、ウェブ バンドルを Capgo チャンネルに送信し、バイナリをビルドするのではなく、説明されているようにします。 Comparing CI/CD platforms for Capacitor apps.

iOS の署名問題が Android のビルドをキャンセルしないようにする

対策： __CAPGO_KEEP_0__はCapacitorアプリ fail-fast: false __CAPGO_KEEP_0__はCapacitorアプリ

strategy:
  fail-fast: false
  matrix:
    platform: [ios, android]

障害: キャッシュなし、または不正なキャッシュ

症状: すべてのビルドはGradle依存関係とCocoaPodsを再度ダウンロードする、またはステージングビルドは古いキャッシュから生産用設定を送信する

対策: キャッシュ ~/.gradle/caches, ~/.gradle/wrapper、そして ios/App/Pods キャッシュはロックファイルに基づいてキー化される。環境を区分することでキャッシュを分割する。Capgo ビルドと組み合わせると、各アプリのビルドキャッシュを分割することができる --cache-key prod そして --cache-key staging、またはキャッシュをスキップしてクリーンビルドを行う --no-cache 障害: モノレポパス

障害: キャッシュなし、または不正なキャッシュ

症状: could not find capacitor.config Nativeプロジェクトからプラグインが欠けている。

Fix: アプリパッケージからCapacitorコマンドを実行し、ツールをホイストされたCapacitor__CAPGO_KEEP_1__に指示します。 node_modules.Capgo CLIを受け入れます。 --path このため。 --node-modules ステージ5: ストアの提出

落とし穴：再利用されたビルド番号

症状:

Symptom: CIで番号を生成します。Fastlaneを使用すると、最新のTestFlightビルドを読み取り、1を加算します。codeビルドでは、デフォルトではApp Store Connectまたは最高のビルド番号を取得します。

Fix: generate the number in CI. With fastlane, read the latest TestFlight build and add one. With Capgo Build, this is the default: it fetches the latest build number from App Store Connect or the highest versionCode Google Playから取得し、増分します。

Pitfall: TestFlightでビルドが止まる

症状: アップロードは成功しますが、テスターはビルドを見ることがありません。

原因: 輸出管理回答が欠けている

対処法: 標準暗号化のみを使用する場合、1度だけ宣言します。 ios/App/App/Info.plist Pitfall: プライバシーマニフェストの拒否

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

プライバシー宣言の拒否

症状: Apple から送信されたメールで、必要な理由 API の宣言が欠けていることを示す ITMS-91053 のエラーが表示されます。

対策: アプリのターゲットに PrivacyInfo.xcprivacy を追加し、独自のプラグインをアップデートする。 プライバシー マニフェスト ガイド for Capacitor アプリ.

落とし穴: 不正確なアーティファクトタイプ

対策: Google Play には AAB (bundleRelease) が必要ですが、APK ではありません。 bundleRelease まだ署名設定がなければ、署名設定を追加してください。そうしないと、Play が署名されていない AAB を拒否します。 release iOS には App Store エクスポートが必要ですが、開発用またはアドホックの IPA ではありません。ビルド ステップでエクスポート方法を確認してください。 signingConfigs.release in android/app/build.gradle Pitfall: wrong artifact type

ステージ6：ライブアップデート

落とし穴：live updateを配信する

症状： オーバー・ザ・エア更新後、インストール済みバイナリに存在しないプラグインメソッドを呼び出してアプリがクラッシュする

原因： ウェブバンドルは、ユーザーのデバイスにインストールされているバイナリに組み込まれているプラグインのバージョンよりも新しいバージョンを依存している

対策： パイプラインに任せる build needed 0を出力する場合、ネイティブ依存関係はチャンネル上でライブにあり、1を出力する場合、新しいバイナリが必要である

if bunx @capgo/cli@latest build needed com.example.app --channel production; then
  bunx @capgo/cli@latest bundle upload com.example.app --channel production
else
  bunx cap sync
  bunx @capgo/cli@latest build request com.example.app --platform ios
  bunx @capgo/cli@latest build request com.example.app --platform android
fi

ネイティブパスを強制することもできる。ファイルが ios/, android/、または capacitor.config.* 変更された場合。パターンは完全に 自動で live update またはネイティブビルドを選択CI/CDのCapacitorの共通の落とし穴 ネイティブ互換性.

最も多くの落とし穴を排除する修正

If you only change one thing, move iOS compilation and signing out of your CI runners. Keychain setup, Xcode upgrades, macOS costs, and profile installation all disappear from your pipeline when a Linux job hands the prepared project to Capgo ビルド:

bun install --frozen-lockfile && bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

The pitfalls in stages 1, 5, and 6 still apply, because they are about your project, not the runner. For more on debugging failing jobs, see Capacitor CI/CD パイプラインでのビルド失敗の修正.

Fixing build failures in __CAPGO_KEEP_0__ CI/CD pipelines