Linux adalah tempat yang nyaman untuk menulis aplikasi Capacitor, dan Android bisa di-build dari sana tanpa kompromi. iOS adalah pengecualian: Xcode dan tools signing Apple hanya berjalan di macOS. Solusinya bukan Mac mini di bawah meja, melainkan generate project iOS secara lokal dan compile di macOS di cloud.
Panduan ini adalah versi Linux dari Build aplikasi iOS dari Windows dengan Capacitor dan Capgo Build. Panduan ini membahas bagian yang berbeda di Linux: sertifikat OpenSSL, Linux shell, dan CI dari Linux runners.
Pembagian tugas
Aplikasi Capacitor memiliki dua build:
- Build web: output framework Anda di
dist/. Selesai di Linux. - Native Build: arsip Xcode, signing, upload. Ditangani oleh Build Capgo di mesin Apple Silicon yang menjalankan macOS dan Xcode versi terbaru.
CLI mengunggah yang sudah disiapkan ios/ proyek dari mesin Anda. Tidak perlu ada di Git host, dan kredensial registry privat tidak keluar dari perangkat Anda, karena instalasi dependensi dan cap sync terjadi secara lokal sebelum upload.
Prerequisites
- Aplikasi Capacitor yang bisa di-build secara lokal (framework apa pun).
- Node 20+ atau Bun di Linux.
- Keanggotaan Apple Developer Program.
- OpenSSL (sudah terinstal secara default di hampir semua distro).
- Akun Capgo dan aplikasi yang sudah terdaftar di
bunx @capgo/cli@latest app add.
1) Generate proyek iOS di Linux
bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios
Anda akan melihat sesuatu seperti Skipping pod install because CocoaPods is not installed. Ini wajar. Folder ios/ tersebut ada dan harus di-commit; folder ini berisi bundle ID, Info.plist, ikon, dan pengaturan native Anda.
2) Sync aset web sebelum setiap build
bun run build
bunx cap sync ios
cap sync menyalin dist/ ke dalam ios/App/App/public dan memperbarui referensi plugin. Capgo mengompilasi apa yang ada di ios/, jadi proyek yang tidak tersinkron akan mengirim UI versi sebelumnya.
3) Buat materi penandatanganan tanpa Mac
Anda membutuhkan tiga hal: sertifikat Apple Distribution sebagai .p12, profil provisioning App Store, dan kunci API App Store Connect. Tidak ada yang memerlukan Keychain Access.
Sertifikat distribusi dengan OpenSSL
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
-subj "/emailAddress=you@example.com/CN=Your Name/C=US"
Unggah ios_distribution.csr di Certificates, Identifiers & Profiles, pilih Apple Distribution, lalu unduh distribution.cer. Konversi dan bundle:
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
-out ios_distribution.p12 -legacy
Panduan -legacy flag penting dengan OpenSSL 3. Tanpanya, tooling Apple akan menolak .p12 dengan error kata sandi tidak valid meskipun kata sandinya benar. Jika Anda lebih memilih tidak menyentuh OpenSSL, gunakan iOS certificate generator kami melakukan hal yang sama di browser.
Provisioning profile dan kunci API
Di Apple Developer portal, buat profil App Store untuk bundle ID Anda yang menggunakan sertifikat baru dan unduh .mobileprovision. Di App Store Connect, buat kunci API dengan peran App Manager dan unduh .p8; catat Key ID dan Issuer ID. Panduan build iOS menampilkan setiap layar.
Ingin memeriksa profil di Linux? openssl smime -inform der -verify -noverify -in profile.mobileprovision menampilkan plist yang tertanam.
4) Simpan kredensial di Capgo
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
--platform ios \
--apple-team-id "TEAMID" \
--apple-key ./AuthKey_KEYID.p8 \
--apple-key-id "KEYID" \
--apple-issuer-id "issuer-uuid" \
--certificate ./ios_distribution.p12 \
--ios-provisioning-profile ./App_Store.mobileprovision
Atau jalankan bunx @capgo/cli@latest build init --platform ios untuk versi panduan. Di Linux, langkah kunci App Store Connect dilakukan secara manual; sisanya dipandu.
Jika Apple menolak kunci dengan error autentikasi, sinkronkan jam Anda. JWT ditandatangani dengan waktu lokal dan Apple menolak token yang selisihnya terlalu jauh:
timedatectl status
sudo timedatectl set-ntp true
5) Minta build
bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
Proyek yang sudah disiapkan ios/ di-upload, Capgo berjalan pod install, mengarsipkan dengan Xcode, menandatangani dengan sertifikat Anda, dan streaming log ke terminal Anda. Dengan kunci API yang dikonfigurasi, build akan dikirim ke TestFlight saat selesai. Instal aplikasi TestFlight di iPhone untuk menjalankannya.
Build yang gagal bisa didiagnosis secara otomatis dengan menambahkan --ai-analytics; diagnosis build AI membaca log Xcode dan menjelaskan perbaikannya.
6) Build ad hoc untuk tester tanpa TestFlight
Untuk perangkat QA yang terdaftar via UDID, gunakan profil Ad Hoc dan simpan IPA sebagai artifact:
bunx @capgo/cli@latest build request com.example.app \
--platform ios \
--ios-distribution ad_hoc \
--output-upload
CLI menampilkan link download yang terbatas waktu. Tambahkan --output-record build.json untuk menyimpan link dan QR code untuk tester.
7) Otomatiskan dari runner CI Linux
Perintah yang sama berjalan di CI Linux mana pun. Contoh GitHub Actions:
name: iOS build
on:
workflow_dispatch:
jobs:
ios:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run build
- run: bunx cap sync ios
- run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
env:
CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
Kredensial yang disimpan di langkah 4 tersimpan di Capgo, jadi runner hanya butuh token. Atau, ekspor CI .env dengan bunx @capgo/cli@latest build credentials manage dan oper nilai sebagai secrets; lihat mengelola kredensial.
8) Iterasi harian tanpa native build
Setelah build TestFlight tersedia, sebagian besar perubahan adalah perubahan web. Push dengan Live Updates Capgo:
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Sisihkan build request untuk penambahan plugin, perubahan izin, perubahan ikon, dan upgrade Capacitor.
Jebakan di Linux
- Lupa
cap sync ios: IPA menampilkan UI lama. Sinkronkan sebelum setiap request. ios/di.gitignore: CLI mengunggah dari disk sehingga tetap bisa build, tapi rekan tim dan CI Anda tidak akan memiliki proyek native. Commit-kan..p12password ditolak: buat ulang dengan-legacy.- Autentikasi Apple gagal: clock drift. Aktifkan NTP.
- Plugin ditambahkan, lupa rebuild native: menambahkan plugin Capacitor akan mengubah binary native. Jalankan cloud build baru dan submit ke store sebelum merilis perubahan web yang memanggilnya.
Ringkasan
Linux tidak bisa menjalankan Xcode, tapi juga tidak perlu. Buat ios/ dengan Capacitor, buat sertifikat build pakai OpenSSL, dan biarkan Capgo Build yang compile, sign, dan kirim ke TestFlight. Dengan Live Updates untuk web layer, tim yang hanya pakai Linux bisa merilis iOS sama rutinnya dengan Android. Untuk setup environment lengkap, baca Development Capacitor di Linux.