Capacitor Masalah iOS yang Umum dan Solusinya

Sebanyak 80% masalah iOS Capacitor jatuh ke dalam lima kategori: alat tukang yang salah, penyelesaian dependensi (SPM atau CocoaPods), kesalahan kompilasi dari plugin, code tanda tangan, dan masalah waktu eksekusi seperti "plugin tidak diimplementasikan" atau layar WebView kosong. Mulai dengan bunx cap doctorKonfirmasi bahwa Anda telah memilih Xcode 26, jalankan bunx cap sync iosdan baca kesalahan pertama di log pembangunan Xcode, bukan yang terakhir.

Pedoman ini menyebutkan kesalahan yang paling sering kita temukan di Capacitor 8 proyek, penyebab masing-masing, dan cara memperbaikinya. Untuk Android, lihat Capacitor Petunjuk Pemecahan Masalah Android.

Daftar Pemeriksaan Cepat

Lakukan hal-hal ini sebelum mengejar kesalahan tertentu:

bunx cap doctor            # Capacitor, CLI and plugin versions should match
node -v                    # 22 or later for Capacitor 8
xcodebuild -version        # 26.x
xcode-select -p            # should point to the Xcode you expect
bun run build && bunx cap sync ios

• Versi: @capacitor/core, @capacitor/ios dan @capacitor/cli harus memiliki versi mayor yang sama. Kesalahan kompile dan runtime yang aneh disebabkan oleh perbedaan versi. Lihat Pemecahan Masalah Kesalahan Versi Capacitor.
• Satu Xcode: jika Anda memiliki beberapa versi Xcode, xcode-select -p menentukan mana yang digunakan oleh CLI. Perbaiki dengan sudo xcode-select -s /Applications/Xcode.app.
• Manajer Paket Mana: jika ada ios/App/CapApp-SPM ada, proyek menggunakan SPM. Jika ios/App/Podfile ada, maka menggunakan CocoaPods.

Masalah alat:

Xcode atau SDK terlalu tua

Gejala: value of type 'WKWebView' has no member 'isInspectable', kesalahan sintaks Swift di dalam Capacitor, atau compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 memerlukan Xcode 26. Di GitHub Actions, macos-latest tidak selalu menunjuk ke gambar dengan Xcode terbaru. Pinlah gambar yang mencakup Xcode 26 dan pilih secara eksplisit:

- run: sudo xcode-select -s /Applications/Xcode_26.0.app

Periksa dokumen gambar runner untuk jalur yang tepat. Untuk kesalahan modul-minimum, naikkan target pengembangan aplikasi ke versi plugin yang paling rendah, atau gunakan versi plugin yang lebih tua.

ITMS-90725: SDK version issue saat mengunggah

Build yang dibuat menggunakan SDK yang lebih tua dari yang diterima Apple saat ini. Sejak 28 April 2026, unggahan harus dibuat dengan Xcode 26 dan iOS 26 SDK. Lihat Persyaratan Xcode 26 dari Apple untuk Capacitor aplikasi. Capgo Build sudah dapat dibangun di Xcode 26 jika Anda tidak ingin menjaga runner Mac.

Erornya Pengelola Paket Swift

Missing package product 'CapApp-SPM'

Xcode belum menyelesaikan paket lokal, atau cache-nya sudah ketinggalan zaman.

1. File > Paket > Reset Cache Paket.
2. File > Packages > Resolve Package Versions.
3. Jika aplikasi telah di migrasikan dari CocoaPods, pastikan CapApp-SPM Jika aplikasi telah dipindahkan dari CocoaPods, periksa bahwa terdaftar di bawah proyek tab dan terkait dengan target Aplikasi.

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

Plugin suatu modul Package.swift menggunakan nama paket atau produk yang tidak sesuai dengan apa yang Capacitor CLI menghasilkan dari nama npm-nya. Ini adalah bug plugin. Perbarui plugin, atau patchnya. Pengembang plugin dapat menemukan aturan penamaan di migrasi plugin Capacitor ke SPM.

“Beberapa plugin yang diinstal Capacitor tidak kompatibel dengan SPM”

Pesan peringatan selama cap sync berarti setidaknya satu plugin tidak memiliki Package.swift. Ini ditinggalkan dari aplikasi, sehingga panggilan kepadanya gagal dengan ‘belum diimplementasikan’. Perbarui plugin, gantilah dengan yang mendukung SPM, atau gunakan CocoaPods untuk sementara waktu.

Identitas paket duplikat atau nama target

Dua plugin memiliki identitas paket atau nama target (seringnya nama umum seperti Plugin. Sejak CLI 8.4 Anda dapat memperbaikinya dari Capacitor konfigurasi:

const config: CapacitorConfig = {
  // ...
  experimental: {
    ios: {
      spm: {
        packageOptions: {
          '@acme/capacitor-foo': { symlink: true },
          '@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
        },
      },
    },
  },
};

symlink membuat CLI mengacu ke plugin melalui folder simlink dengan jalur unik. moduleAliases mengganti nama modul yang bersaing untuk ketergantungan tersebut. Laporkan konflik ke atas juga.

Tidak edit CapApp-SPM/Package.swift

CLI menggantinya setiap saat. Perubahan lokal hilang. Gunakan opsi konfigurasi saja. experimental.ios.spm opsi konfigurasi.

Anda membuka

No such module 'Capacitor'

sebaliknya App.xcodeproj Gunakan App.xcworkspace. Use bunx cap open iosJika workspace masih terbuka dan kesalahan tetap berlanjut, jalankan bunx cap sync ios reinstall pods.

CocoaPods could not find compatible versions for pod "X"

Kedua penyebab:

1. Repo spesifikasi ketinggalan zaman: jalankan cd ios/App && pod install --repo-update.
2. Pin yang bertentangan: dua plugin memerlukan versi yang tidak kompatibel dari pod yang sama. Error mencetak rantai. Perbarui plugin dengan pin yang ketat, sesuaikan versi (untuk Firebase, jaga semua plugin Firebase pada versi SDK yang sama), atau patch podspec.

Jika masih gagal, hapus ios/App/Podfile.lock dan ios/App/Pods, lalu sinkron ulang. Ini juga akan memperbarui setiap pod, jadi tes setelahnya.

The sandbox is not in sync with the Podfile.lock

Jalankan bunx cap sync iosTerjadi setelah perubahan cabang atau instalasi parsial.

Unable to find compatibility version string for object version '70'

Jalankan project.pbxproj Menggunakan format yang tidak dapat dibaca oleh versi CocoaPods Anda. Perbarui CocoaPodsbrew upgrade cocoapods atau tingkatkan di dalamnya Gemfile. Sebagai langkah terakhir, lindungi file dan turunkan objectVersion.

Sandbox: rsync(...) deny(1) file-write-create

Xcode's sandboxing skrip pengguna menghalangi skrip CocoaPods framework embed. Pengaturan Build > Sandi Skrip Pengguna to ke di target aplikasi.

could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'

Pembangunan simulator sedang berjalan untuk Intel. Pada Apple Silicon, biasanya berarti Xcode menjalankan di bawah Rosetta atau versi lama EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 Pengaturan itu merupakan sisa dari suatu kerja sebelumnya. Jalankan Xcode secara native, hapus pengaturan tersebut dari target App dan setiap post_install bersihkan dan bangun kembali.

Kesalahan Pengekompilan

Command PhaseScriptExecution failed with a nonzero exit code

ini adalah wrapper. Perluas fase pembangunan gagal di navigator Laporan dan baca hasil skrip. Penyebab umum di Capacitor aplikasi:

• A Run Script memerlukan node dan Xcode tidak dapat menemukannya karena Xcode tidak memuat profil shell Anda dan Node diinstal dengan nvm, fnm atau Volta. Gunakan jalur lengkap ke node di skrip, atau export PATH di bagian atasnya
• Skrip unggah laporan kegagalan (Sentry, Crashlytics) kekurangan kreditensial di CI.
• CocoaPods embed skrip diblokir oleh pengguna skrip sandboxing (lihat di atas).

'X' is only available in iOS 16.0 or newer

A plugin menggunakan API di atas target pengembangan Anda. Naikkan target di Xcode, di Podfile (platform :ios, '16.0'jika Anda menggunakan CocoaPods, dan periksa README plugin untuk minimumnya.

Kesalahan konkurensi Swift 6 di plugin

Pesan seperti Sending 'x' risks causing data races muncul ketika plugin atau target aplikasi Anda menggunakan mode bahasa Swift 6. Capacitor 8 tidak secara resmi mendukung Swift 6. Tahan target aplikasi pada mode bahasa Swift 5 sampai plugin diperbarui.

Code penandatanganan

Signing for "App" requires a development team

Buka Target Aplikasi > Tanda Tangan & Kemampuan dan pilih tim. Di CI, lakukan DEVELOPMENT_TEAM ke xcodebuild atau gunakan alat tanda tangan. Jika kesalahan menyebutkan sumber daya bundle pod daripada Aplikasi, matikan tanda tangan untuk target bundle di Podfile post_install hook.

Provisioning profile "X" doesn't include the ... entitlement

Anda menambahkan kemampuan (Pemberitahuan Push, Domain yang Terkait, Masuk dengan Apple) tanpa menghasilkan profil kembali. Aktifkan di portal Pengembang Apple, lalu refresh profil. Kami memiliki penghasil sertifikat iOS untuk membuat sertifikat tanpa menari dengan keychain Mac, dan pencari ID UDID untuk mendaftarkan perangkat uji

Unable to install "App" di perangkat

aktifkan Mode Pengembang pada perangkat (Pengaturan > Privasi & Keamanan > Mode Pengembang), percayakan sertifikat pengembang, dan pastikan ID UDID perangkat ada dalam profil pengembangan untuk build pengembangan.

kesalahan waktu eksekusi

"X" plugin is not implemented on ios

JavaScript sisi tidak menemukan implementasi native. Periksa dalam urutan:

1. plugin ini ada di package.json and you ran bunx cap sync ios setelah menginstalnya.
2. Untuk SPM: plugin ini muncul di ios/App/CapApp-SPM/Package.swiftJika tidak, plugin ini tidak memiliki Package.swift.
3. Untuk CocoaPods: plugin ini muncul di blok Podfile dan capacitor_pods dan tidak ada peringatan cetak. pod install tidak ada peringatan yang dicetak.
4. Kamu tidak memiliki dua plugin yang mendaftarkan nama JS yang sama (misalnya dua plugin notifikasi push).
5. WKAppBoundDomains tidak ada di Info.plist, atau jika ada, limitsNavigationsToAppBoundDomains tertentu dan localhost terdaftar. Domain aplikasi menghalangi injeksi skrip plugin lainnya.
6. Hapus folder build yang lama dan bangun kembali. Build yang usang menyimpan registrasi plugin lama.

layar putih kosong pada peluncuran

Pertama-tama, gunakan Inspektor Web Safari untuk memeriksa WebView. Layar putih kosong kebanyakan merupakan kesalahan JavaScript.

• salah webDir: capacitor.config.ts mengarah ke folder yang tidak mengandung index.htmlPeriksa ios/App/App/public.
• Target build terlalu baru: bundler Anda menghasilkan sintaks yang lebih tua yang tidak didukung oleh WebKit. iOS 15 adalah minimum untuk Capacitor 8, jadi target safari15 atau lebih tinggi di Vite/esbuild dan periksa kembali browserslist.
• Jalur aset absolut: sebuah base diatur ke CDN atau subpath di konfigurasi bundler Anda akan mengganggu pengisian lokal.
• Live reload tidak dapat dijangkau: server pengembang harus mendengarkan IP LAN Anda (--host 0.0.0.0), ponsel harus berada di jaringan yang sama, dan aplikasi memerlukan izin Jaringan Lokal izin akses (Pengaturan > Privasi & Keamanan > Jaringan Lokal). Hapus server.url di hapus dari konfigurasi sebelum dibuat.
• Live update bundle rusak: jika aplikasi menggunakan OTA updates, bundle yang rusak dapat membuat layar menjadi kosong. Capgo’s updater akan kembali secara otomatis ketika notifyAppReady() tidak dipanggil tepat waktu. Lihat dokumen pembarui. docs pembarui.

Isi di bawah notch atau indikator home

Tambahkan viewport-fit=cover ke tag meta viewport Anda dan tambahkan dengan env(safe-area-inset-top) dan env(safe-area-inset-bottom). Capacitor 8’s Plugin Bar Sistem Kontrol gaya dan visibilitas status bar pada kedua platform.

Penggunaan keyboard menutupi input

Konfigurasi plugin Plugin Kibor resize mode (native, body, ionic atau nonedan tes pada perangkat nyata. Simulator menangani keyboard dengan cara yang berbeda.

kesalahan App Store Connect

• ITMS-91053: Missing API declaration: aplikasi atau plugin Anda menggunakan API yang diperlukan tanpa entri manifest privasi. Tambahkan PrivacyInfo.xcprivacy ke target App dengan alasan-alasan, dan update plugin yang mengirimkan manifest sendiri.
• ITMS-90725: SDK version issue: bangun ulang dengan Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': kerangka kerja terintegrasi di dalam ekstensi atau kerangka kerja lainnya. Periksa Embed pengaturan untuk ekstensi aplikasi.

Bagaimana mengatasi ketika kesalahan tidak terdaftar

1. Inspektor Web Safari untuk kesalahan JS dan panggilan jaringan. Bangun debug dapat dilihat pada iOS 16.4+. Untuk bangun rilis, atur ios.webContentsDebuggingEnabled: true secara sementara.
2. Konsol Xcode untuk log asli, termasuk Capacitor’s ⚡️ pesan jembatan yang menampilkan setiap panggilan plugin.
3. Terminal dengan perangkat yang dipilih untuk crash dan log sistem.
4. IsolateBuatlah aplikasi baru dengan bun create @capacitor/appTambahkan hanya plugin yang diduga, dan lihat apakah kesalahan tersebut dapat direproduksi.

The ultimate guide to debugging Capacitor apps menggali lebih dalam ke dalam setiap alat. Jika penyebab utama adalah bug plugin, maka patch biasanya adalah cara paling cepat untuk melepaskan blokir sementara Anda menunggu rilis.