CI/CD untuk Capacitor: Kesalahan Umum dan Perbaikan

Sebagian besar kesalahan CI/CD untuk Capacitor berasal dari daftar singkat yang sama: tanda tangan iOS code, perangkat lunak macOS yang hilang atau ketinggalan zaman, konstruksi web yang tidak pernah masuk ke proyek native, nomor konstruksi yang digunakan kembali, dan persyaratan toko yang gagal hanya pada saat unggah.

Jika Anda sedang mengatur pipeline dari awal, baca Setting up CI/CD untuk aplikasi Capacitor Stage 1: Membangun layer web

Pitfall: aplikasi native mengirimkan konstruksi web yang lama

Kebijakan: Aplikasi asli mengirimkan versi web yang lama

Peran: Pengulas Sukses CI, aplikasi terinstal, tapi menampilkan UI kemarin.

Penyebab: cap sync mengambil apa saja yang ada di webDir Saat itu. Jika pipeline dijalankan cap sync sebelum build web, atau build web menulis ke folder yang berbeda dari webDir di capacitor.config.tsprojek native menjadi ketinggalan file.

Pembahasan: Jalankan selalu langkah-langkah dalam urutan ini, dan gagal jika folder keluaran kosong.

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

Pastikan webDir cocok dengan hasil output bundler Anda ("dist untuk Vite, www untuk Angular dengan Ionic, build untuk beberapa pengaturan React).

Kebijakan: URL server pengembang dibiarkan di konfigurasi

Gejala: layar rilis menampilkan layar kosong atau mencoba memuat http://192.168.x.x:5173.

Pemicu: server.url dalam capacitor.config.ts ditetapkan untuk reload hidup dan dikomit.

Fix: tidak pernah mengomit server.url. Baca dari variabel lingkungan yang dibaca oleh CI:

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

Kebijakan: variabel lingkungan dibakar pada waktu yang salah

Gejala: Produksi aplikasi berbicara ke API pengujian.

Penyebab: Vite, webpack, dan variabel lingkungan Angular inline di waktu pembangunan. Nilai yang ada ketika bun run build dijalankan adalah satu di dalam biner, dan di live update apa pun yang dibangun dari pekerjaan yang sama.

Pembaharuan: atur variabel lingkungan spesifik aplikasi sebelum pembangunan web, per pekerjaan, dan bangun bundle terpisah untuk pengujian dan produksi. Jangan mencoba untuk menggantinya setelah cap sync.

Kebakaran: Drift file lock

Gejala: Versi plugin di CI berbeda dari yang ada di komputer Anda, dan kompilasi native gagal dengan simbol yang hilang.

Pembaharuan: commit file lock dan instal dengan bun install --frozen-lockfile atau npm ci. Pin @capacitor/core, @capacitor/ios, @capacitor/android, dan @capacitor/cli ke versi yang sama. Versi yang tidak sesuai sering menyebabkan kesalahan native; lihat Fix kesalahan versi Capacitor.

Langkah 2: Alat toolchain native

Kebocoran: versi Node, JDK, atau Xcode yang salah

Gejala: Unsupported class file major version, The engine "node" is incompatible, atau kesalahan Xcode tentang SDK fitur.

Penyebab: gambar runner yang dihosting berubah, dan Capacitor 8 memiliki minimum yang ketat.

Fix: pastikan setiap versi secara eksplisit di pipeline daripada mengandalkan 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'

Pitfall: membangun terhadap Xcode Apple tidak lagi menerima

Gejala: kesalahan unggah dengan pesan bahwa aplikasi dibangun dengan SDK yang tidak didukung.

Cause: sejak tanggal 28 April 2026, App Store Connect memerlukan Xcode 26 dan iOS 26 SDK. Mesin Mac yang dihosting sendiri dan gambar runner yang lebih tua masih menggunakan Xcode 16.

Fix: pilih macos-26 gambar atau instal Xcode 26 pada runner Anda. Detail dalam kebutuhan Xcode 26 Apple untuk Capacitor aplikasi.

Pitfall: kebingungan CocoaPods dan SPM

Gejala: xcodebuild: error: 'App.xcworkspace' does not exist, atau pods tidak ditemukan.

Cause: projek Capacitor baru 8 menggunakan Swift Package Manager dan dibangun ios/App/App.xcodeproj. Projek yang lebih tua menggunakan CocoaPods dan membangun ios/App/App.xcworkspace setelah pod install. Pipelines yang dicopy dari tutorial yang lebih tua mengasumsikan workspace.

Fix: periksa mana yang digunakan oleh projek Anda dan bangun file yang tepat. Jika Anda sedang melakukan migrasi, lihat Bagaimana cara migrasi aplikasi Capacitor Anda ke SPM.

Pitfall: Plugin Android membangun break setelah upgrade Gradle

Gejala: Namespace not specified, package attribute is deprecated, atau kesalahan dari plugin’s build.gradle setelah memperbarui Android Studio.

Fix: tahan Android Gradle Plugin di android/build.gradle, lakukan upgrade pada cabang, dan update plugin terlebih dahulu. Kesalahan spesifik akan dibahas di Perbaiki Capacitor plugin build error dengan AGP 9.

Langkah 3: Code signing

Kebijakan: Signing iOS hanya berfungsi di Mac Anda

Gejala: No signing certificate "iOS Distribution" found, No profiles for 'com.example.app' were foundatau errSecInternalComponent.

Pemicu: Kunci Mac Anda menyimpan sertifikat dan Xcode mengunduh profil untuk Anda. Runner CI tidak memiliki kunci tersebut, dan kunci Mac Anda terkunci dalam sesi non-interaktif.

Perbaiki: Import sertifikat ke kunci sementara yang tidak terkunci dan instal profil di mana Xcode 16 dan seterusnya mencari:

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/"

Pilih nama identitas Apple Distribution, bukan versi lama iOS Distribution. fastlane’s 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.

Bahaya: sertifikat yang telah kedaluwarsa atau dibatalkan

Symptom: salah satu aliran yang berfungsi selama setahun tiba-tiba gagal.

Cause: Apple distribution certificates and provisioning profiles expire after a year. A teammate creating a new certificate in Xcode can also invalidate the profile your CI uses.

Fix: Tetapkan tanggal kadaluarsa di kalender tim Anda, gunakan satu sertifikat distribusi bersama untuk CI, dan periksa sebelum membangun. bunx @capgo/cli@latest build prescan --platform ios memeriksa kedaluwarsa sertifikat, kata sandi, dan penggabungan profil sebelum apa pun diunggah.

Pitfall: Apple ID logins and two-factor prompts

Gejala: fastlane menunggu terus kode code 6 digit.

Pembetulan: gunakan kunci App Store Connect API (".p8, key ID, issuer ID) instead of an Apple ID and password. It does not require two-factor authentication and can be scoped to App Manager. If authentication still fails with a correct key, check the runner clock: the token is signed with the local time, and Apple rejects tokens with a skewed timestamp.

Kebijakan: rahasia base64 yang tidak dapat diuraikan

Gejala: MAC verification failed, invalid keystore formatPenyebab: base64: invalid input.

Cause: yang dibuat dengan OpenSSL 3 default yang tidak dapat dibaca oleh macOS. .p12 Gejala: fastlane menunggu terus kode __CAPGO_KEEP_0__ 6 digit.

Pembetulan: kodekan dalam satu baris, dan gunakan -legacy ketika membuat sebuah .p12 dengan 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

Pitfall: keystore Android hilang

Gejala: anda tidak dapat menandatangani pembaruan karena tidak ada yang memiliki keystore.

Fix: dengan Play App Signing, keystore adalah kunci unggahan, dan dukungan Play Console dapat mendaftarkan satu baru. Simpan keystore di rahasia CI Anda dan cadangan offline. Jangan biarkan hidup hanya di satu laptop. Generator keystore Android membuat yang baru jika Anda baru saja memulai.

Level 4: Desain Pipa

Pitfall: bangun asli pada setiap permintaan pull

Gejala: cek PR yang lambat dan tagihan macOS menit yang besar.

Penyebab: Build iOS di pengguna macOS yang dihosting adalah menit yang paling mahal di kebanyakan rencana CI, dan kebanyakan komit hanya menyentuh JavaScript.

Pembetulan: jalankan lint, tes, dan build web di setiap PR. Jalankan build native di tag rilis atau merge untuk mainUntuk pratinjau PR, kirimkan bundle web ke sebuah Capgo saluran bukan membuat sebuah biner, seperti yang dijelaskan di Menggambarkan Platform CI/CD untuk Aplikasi Capacitor.

Kebocoran: Membangun iOS dan Android Secara Berurutan

Pembetulan: agar masalah tanda tangan iOS tidak membatalkan build Android yang baik. fail-fast: false Masalah tanda tangan iOS tidak akan membatalkan pembangunan Android yang baik.

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

Pitfall: tidak ada caching, atau cache yang salah

Gejala: setiap build mengunduh dependensi Gradle dan CocoaPods dari awal, atau build produksi dikirim dari cache yang ketinggalan zaman.

Solusi: cache ~/.gradle/caches, ~/.gradle/wrapper, dan ios/App/Pods terkunci pada file lock. Bagi cache berdasarkan lingkungan. Dengan Capgo Build, cache build per aplikasi dapat dipisahkan dengan --cache-key prod dan --cache-key staging, atau dilewati dengan --no-cache untuk mendapatkan build yang bersih.

Pitfall: jalur monorepo

Gejala: could not find capacitor.config atau plugin yang hilang dari proyek native.

Fix: jalankan perintah Capacitor dari paket aplikasi, dan arahkan tools ke __CAPGO_KEEP_1__ node_modulesThe Capgo CLI menerima --path and --node-modules dan

Langkah 5: Simpan Pengajuan

Stage 5: Pengiriman ke Toko

Symptom: "“Versi bundle harus lebih tinggi dari versi yang telah diunggah sebelumnya” di iOS, atau “Versi code telah digunakan sebelumnya” di Google Play.”

Fix: “Versi bundel harus lebih tinggi dari versi yang telah diunggah sebelumnya” di iOS, atau “Versi Capgo telah digunakan sebelumnya” di Google Play.” versionCode dari Google Play dan meningkatkan itu.

Pitfall: bangunan terjebak di TestFlight

Gejala: upload berhasil tetapi tes tidak pernah melihat bangunan.

Penyebab: jawaban kewajiban ekspor hilang.

Perbaikan: deklarasikan sekali di ios/App/App/Info.plist jika Anda hanya menggunakan enkripsi standar:

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

Pitfall: penolakan manifesto privasi

Gejala: email dari Apple tentang alasan yang diperlukan yang hilang API deklarasi (ITMS-91053).

Perbaiki: tambahkan PrivacyInfo.xcprivacy ke app target dan perbarui plugin yang membawa sendiri. Lihat Petunjuk Privasi untuk Aplikasi Capacitor.

Google Play membutuhkan AAB (

Perbaiki: Google Play memerlukan AAB (bundleReleasetidak merupakan APK. bundleRelease tetap berhasil tanpa release konfigurasi signing dan menghasilkan AAB tidak terdaftar yang ditolak oleh Play, jadi konfigurasi signingConfigs.release in android/app/build.gradle Pertama. iOS memerlukan ekspor ke App Store, bukan IPA pengembangan atau ad hoc. Periksa metode ekspor di langkah pembangunan Anda.

Langkah 6: Perbaruan Langsung

Pitfall: mengirimkan live update yang memerlukan bangunan native baru

Gejala: setelah perbaruan over-the-air, aplikasi bermasalah saat memanggil metode plugin yang tidak ada di binary yang terinstal.

Penyebab: bundle web bergantung pada versi plugin yang lebih baru daripada yang dikompilasi ke dalam aplikasi di perangkat pengguna.

Fix: biarkan pipeline memutuskan. build needed keluar 0 ketika dependensi native sesuai dengan apa yang hidup di channel dan 1 ketika binary baru diperlukan:

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

Juga paksa jalur native ketika file di ios/, android/, atau capacitor.config.* berubah. Pola lengkap ada di Pilih otomatis live update atau build asli, dan aturan kompatibilitas ada di kompatibilitas asli.

Perbaikan yang menghilangkan banyak kelemahan

Jika Anda hanya mengubah satu hal, pindahkan kompilasi dan tanda tangan iOS keluar dari runner CI Anda. Pengaturan Keychain, pembaruan Xcode, biaya macOS, dan instalasi profil semua hilang dari pipeline Anda ketika pekerjaan Linux menyerahkan proyek yang disiapkan ke Capgo Bangun:

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 Mengatasi gagal bangun di Capacitor pipeline CI/CD.

Referensi Cepat