Capacitor iOS Mengatasi Masalah: Kesalahan Umum dan Perbaikan

Sebagian besar masalah Capacitor iOS dapat dikategorikan ke dalam lima kelompok: pengaturan alat yang salah, penyelesaian dependensi (SPM atau CocoaPods), kesalahan kompilasi dari plugin, code tanda tangan, dan masalah waktu eksekusi seperti "plugin tidak diimplementasikan" atau WebView kosong. Mulailah dengan bunx cap doctorPastikan Anda telah memilih Xcode 26, jalankan bunx cap sync ios, dan baca kesalahan pertama di log pembangunan Xcode, bukan yang terakhir.

Daftar ini mencantumkan kesalahan yang paling sering kita temukan di Capacitor 8 proyek, penyebab masing-masing, dan perbaikan. Untuk Android, lihat Capacitor Panduan Mengatasi Masalah Android.

Daftar Pemeriksaan Cepat

Lakukan hal-hal ini sebelum mencari kesalahan spesifik:

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 must share the same major. Mismatches cause odd compile and runtime errors. See fix Capacitor version mismatch errors.
• Satu Xcode: jika Anda memiliki beberapa versi Xcode, xcode-select -p Xcode mana yang digunakan oleh CLI. Perbaiki dengan sudo xcode-select -s /Applications/Xcode.app.
• Pengelola Paket: jika ios/App/CapApp-SPM ada, proyek menggunakan SPM. Jika ios/App/Podfile ada, maka menggunakan CocoaPods.

Kesalahan Toolkit

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 yang paling baru. 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, tingkatkan target pengembangan aplikasi ke versi plugin yang paling rendah, atau gunakan versi plugin yang lebih tua.

ITMS-90725: SDK version issue saat mengunggah

Proses pembangunan telah dilakukan dengan SDK yang lebih tua dari yang diterima oleh Apple. Sejak tanggal 28 April 2026, unggahan harus dibangun dengan Xcode 26 dan iOS 26 SDK. Lihat Persyaratan Xcode 26 dari Apple untuk Capacitor. Capgo Pembangunan sudah dapat dibangun di Xcode 26 jika Anda tidak ingin menjaga runner Mac.

Manager Paket Swift error

Missing package product 'CapApp-SPM'

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

1. File > Paket > Reset Cache Paket.
2. File > Paket > Terjemahkan Versi Paket.
3. Jika aplikasi telah dipindahkan dari CocoaPods, periksa bahwa CapApp-SPM terdaftar di bawah proyek's Penggantian Paket tab dan terhubung ke target App.

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

Penggunaan plugin 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 perbaikinya. Pengembang plugin dapat menemukan aturan penamaan di migrasikan sebuah Capacitor plugin ke SPM.

“Beberapa plugin Capacitor yang terinstal tidak kompatibel dengan SPM”

Pesan peringatan ini berarti cap sync maksudnya setidaknya satu plugin tidak memiliki Package.swift. Ini ditinggalkan dari aplikasi, sehingga panggilan ke itu gagal dengan ‘tidak diimplementasikan’. Perbarui plugin, ganti dengan satu yang mendukung SPM, atau gunakan CocoaPods untuk sementara waktu.

Identitas paket duplikat atau nama target

Dua plugin memiliki identitas paket atau nama target yang sama (seringnya sebuah nama umum seperti Plugin). Sejak CLI 8.4 Anda bisa memperbaikinya dari konfigurasi Capacitor:

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 simbolik dengan jalur unik. moduleAliases mengganti nama modul yang bersaing untuk dependensi tersebut. Laporkan konflik ke atas juga.

Jangan edit CapApp-SPM/Package.swift

Setiap CLI memperbarui kode pada setiap sinkronisasi. Perubahan lokal hilang. Gunakan experimental.ios.spm opsi konfigurasi.

Masalah CocoaPods

No such module 'Capacitor'

Anda membuka App.xcodeproj sebaliknya dari App.xcworkspace. Gunakan bunx cap open ios. Jika workspace masih terbuka dan masalah tetap berlanjut, jalankan bunx cap sync ios untuk memasang ulang pods.

CocoaPods could not find compatible versions for pod "X"

Ada dua penyebab:

1. Repo spesifikasi ketinggalan zamanJalankan cd ios/App && pod install --repo-update.
2. Pins yang bertentangan: dua plugin memerlukan versi yang tidak kompatibel dari pod yang sama. Error mencetak rantai. Perbarui plugin dengan pin 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 lagi. 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'

Your project.pbxproj uses a format your CocoaPods version can’t read. Update CocoaPods (brew upgrade cocoapods atau tambahkan versi terbaru di dalam proyek Anda GemfileSebagai langkah terakhir, buatlah salinan file dan turunkan versinya. objectVersion.

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

Sandboxing skrip pengguna Xcode menghalangi skrip integrasi CocoaPods. Jika masalah build pada iOS masih terjadi, hapus ke Tidak di Target Aplikasi.

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

Simulator build untuk Intel sedang berjalan. Pada Apple Silicon, hal ini 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.

Sebuah Skrip Jalankan memerlukan

Command PhaseScriptExecution failed with a nonzero exit code

Berikut adalah instruksi untuk memecahkan masalah. Klik pada fase build yang gagal di navigator Laporan dan baca hasil script. Penyebab umum di aplikasi Capacitor:

• dalam skrip, atau export node and Xcode can’t find it, because Xcode doesn’t load your shell profile and Node is installed with nvm, fnm or Volta. Use the full path to node dalam skrip, atau ekspor PATH di bagian atasnya
• A skrip pengiriman laporan kejadian (Sentry, Crashlytics) tidak memiliki kreditensi di CI.
• CocoaPods embed script diblokir oleh pengguna sandboxing (lihat di atas).

'X' is only available in iOS 16.0 or newer

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

Kesalahan koncurrency 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 di mode bahasa Swift 5 sampai plugin diperbarui.

Code tanda tangan

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 pesan kesalahan menyebutkan sumber bundle pod daripada App, matikan tanda tangan untuk target bundle di Podfile post_install hook.

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

Kamu menambahkan kemampuan (Pemberitahuan Push, Domain Terkait, Masuk dengan Apple) tanpa menghasilkan kembali profil. Aktifkan di portal pengembang Apple, lalu refresh profil. Bantuan kami penghasil sertifikat iOS membantu membuat sertifikat tanpa menari dengan keychain Mac, dan penemuan ID UDID membantu mendaftarkan perangkat uji.

Unable to install "App" di perangkat

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

kesalahan waktu runtime

"X" plugin is not implemented on ios

Bagian JavaScript tidak menemukan implementasi native. Periksa dalam urutan:

1. aplikasi plugin ada di package.json and you ran bunx cap sync ios Setelah Anda menginstalnya.
2. Untuk SPM: plugin tersebut muncul di ios/App/CapApp-SPM/Package.swiftJika tidak, maka plugin tersebut tidak memiliki Package.swift.
3. Untuk CocoaPods: plugin tersebut muncul di blok Podfile dan capacitor_pods dan tidak ada peringatan apa pun. pod install tidak ada peringatan yang dicetak.
4. Anda tidak memiliki dua plugin yang mendaftarkan nama JS yang sama (misalnya dua plugin notifikasi push).
5. WKAppBoundDomains , atau jika ada, Info.plistdiatur dan limitsNavigationsToAppBoundDomains Ditentukan dan localhost App-bound domains tidak memblokir injeksi skrip plugin.
6. Hapus folder build yang lama dan bangun kembali. Build yang usang menyimpan registrasi plugin yang lama.

Blank screen putih saat peluncuran

Pertama-tama, gunakan Safari Web Inspector untuk memeriksa WebView. Sebagian besar layar kosong disebabkan oleh kesalahan JavaScript.

• Salah webDir: capacitor.config.ts menunjuk 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 baru di Vite/esbuild dan periksa browserslist.
• Jalur aset absolut: sebuah base set ke CDN atau subpath di konfigurasi bundler Anda akan mengganggu penggunaan lokal.
• Live reload tidak dapat diakses: server dev harus mendengarkan di IP LAN Anda (--host 0.0.0.0), ponsel harus terhubung ke jaringan yang sama, dan aplikasi memerlukan Jaringan Lokal izin akses (Pengaturan > Privasi & Keamanan > Jaringan Lokal). Hapus server.url __CAPGO_KEEP_0__ bundle rusak
• Live update bundle rusakJika aplikasi menggunakan update OTA, maka bundle yang rusak dapat membuat layar menjadi kosong. Capgo akan secara otomatis melakukan rollback ketika notifyAppReady() tidak dipanggil tepat waktu. Lihat Dokumen Pembaruan.

Konten di bawah notch atau indikator rumah

context viewport-fit=cover kepadatan tag meta viewport dan tambahkan env(safe-area-inset-top) dan env(safe-area-inset-bottom). Capacitor Pengaturan Bar Status 8 mengontrol gaya dan visibilitas bar status pada kedua platform.

Keyboard menutupi input

Konfigurasi plugin Plugin Kibor resize mode (native, body, ionic atau none) dan tes pada perangkat nyata. Simulator menangani keyboard secara berbeda.

Masalah App Store Connect

• ITMS-91053: Missing API declaration: aplikasi Anda atau plugin menggunakan alasan yang diperlukan API 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: Rebuild dengan Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': Periksa apakah suatu framework tersembunyi di dalam ekstensi atau framework lainnya. Periksa : Embed : Pengaturan untuk ekstensi aplikasi.

: Bagaimana cara debug ketika kesalahan tidak terdaftar

1. : Safari Web Inspector : untuk kesalahan JS dan panggilan jaringan. Debug build dapat diperiksa di iOS 16.4+. Untuk release build, atur ios.webContentsDebuggingEnabled: true temporarily.
2. : yang menampilkan setiap panggilan plugin. untuk log asli, termasuk Capacitor’s ⚡️ pesan jembatan yang menampilkan setiap panggilan plugin.
3. : Console.app bersama perangkat yang dipilih untuk crash dan log sistem.
4. Isolasi: buat aplikasi baru dengan bun create @capacitor/app, tambahkan hanya plugin yang diduga, dan lihat apakah kesalahan mereproduksi.

The ultimate guide to debugging Capacitor apps pergi lebih dalam ke setiap alat. Jika penyebab utama adalah bug plugin, sebuah patch biasanya adalah unblock yang paling cepat sementara Anda menunggu rilis.