Cara Baiki Kegagalan Deploy Vercel: Isu Utama Pasukan Malaysia

Vercel adalah platform yang hebat untuk melancarkan aplikasi web moden. Integrasinya dengan 'framework' seperti Next.js, SvelteKit, dan Nuxt menjadikannya pilihan utama untuk pembangun perisian di Malaysia. Walau bagaimanapun, di sebalik kemudahannya, ia boleh menyembunyikan isu yang kompleks apabila proses 'deployment' gagal. Mesej ralat yang dipaparkan tidak selalunya jelas, menyebabkan sesi 'debugging' menjadi rumit.

Di JRV Systems, kami telah membantu banyak syarikat di Malaysia membina dan melancarkan aplikasi mereka di Vercel. Sepanjang tahun lepas, kami mendapati ada beberapa masalah yang sering berulang. Artikel ini akan menghuraikan kegagalan 'deploy' Vercel yang paling lazim kami temui dan langkah-langkah praktikal untuk menyelesaikannya.

Kegagalan Lazim 'Deploy' Vercel dan Cara Membaikinya

Kegagalan 'deployment' boleh berlaku pada peringkat 'build' (binaan) atau 'runtime' (semasa jalanan). Kuncinya adalah dengan memeriksa log secara sistematik—mula-mula log 'Build', dan jika ia berjaya, periksa pula log 'Functions' atau 'Runtime' untuk sebarang ralat di bahagian 'server'. Berikut adalah isu-isu yang paling kerap kami lihat.

1. Pembolehubah Persekitaran (Environment Variables) Tidak Sepadan

Ini adalah isu yang paling kerap berlaku. Aplikasi anda berjalan lancar di mesin tempatan menggunakan fail .env.local, tetapi gagal berfungsi di Vercel.

• Masalah: Vercel tidak membaca fail .env.local anda. 'Environment variables' mesti dikonfigurasi secara terus di papan pemuka projek Vercel untuk persekitaran yang berbeza: Production, Preview, dan Development.
• Penyelesaian: Pergi ke Project Settings > Environment Variables. Tambah setiap pembolehubah yang diperlukan (cth., DATABASE_URL, API_KEY) dan pilih persekitaran yang berkenaan. Untuk pembangunan tempatan yang menyerupai tetapan Vercel, gunakan arahan Vercel CLI vercel env pull .env.local untuk menghasilkan fail tempatan dengan pembolehubah yang telah anda tetapkan di papan pemuka untuk persekitaran 'Development'.

2. 'Git Author' Tidak Sepadan dalam Skop Pasukan (Team Scope)

Seorang pembangun perisian baru menyertai pasukan anda di Seremban, membuat 'commit' pertamanya, dan 'deployment' terus disekat.

• Masalah: Integrasi Git Vercel untuk akaun Pasukan (Team) memerlukan alamat e-mel individu yang membuat 'commit' untuk didaftarkan sebagai pengguna dalam Pasukan Vercel tersebut. Jika git config user.email tempatan mereka menggunakan e-mel peribadi (cth., emel-peribadi@gmail.com) tetapi akaun Vercel mereka menggunakan e-mel kerja (dev@syarikatanda.my), Vercel akan menolak 'push' tersebut.
• Penyelesaian: Pembangun tersebut mesti menyelaraskan konfigurasi Git tempatan mereka dengan e-mel akaun Vercel. Mereka boleh menetapkannya untuk repositori tersebut dengan menjalankan git config user.email "dev@syarikatanda.my" di dalam folder projek.

3. Pengesanan Automatik 'Framework' yang Salah

Sistem binaan Vercel agak pintar, tetapi kadangkala tekaannya salah, terutamanya dengan 'monorepo' atau struktur projek yang tidak standard.

• Masalah: Vercel mungkin mengesan projek anda secara automatik sebagai 'Create React App' biasa, sedangkan ia sebenarnya adalah aplikasi Next.js yang terletak di dalam subdirektori (cth., packages/web). Ini menyebabkan arahan binaan yang salah dilaksanakan, lantas menggagalkan proses 'build'.
• Penyelesaian: Dalam Project Settings, pergi ke bahagian 'General' dan cari 'Build & Development Settings'. Ganti ('override') 'Framework Preset' dan tetapkan secara manual 'Build Command' (cth., next build), 'Output Directory' (cth., .next), dan 'Root Directory' jika aplikasi anda tidak berada di akar repositori.

4. Isu Cache 'Incremental Static Regeneration' (ISR)

Pasukan pemasaran anda mengemas kini kandungan dalam CMS (seperti Strapi atau Contentful), tetapi perubahan tersebut tidak muncul di laman Next.js anda, walaupun selepas tempoh revalidate tamat.

• Masalah: Sistem 'caching' Vercel untuk ISR sangat berkuasa tetapi kadangkala boleh menyajikan kandungan yang lama. Bergantung semata-mata pada 'revalidation' berasaskan masa boleh jadi tidak menentu.
• Penyelesaian: Laksanakan 'on-demand revalidation'. Cipta satu laluan API yang selamat dalam aplikasi Next.js anda (cth., /api/revalidate). Laluan ini, apabila dipanggil, akan memberitahu Vercel untuk membersihkan 'cache' bagi halaman tertentu. Kemudian, konfigurasikan 'webhook' dalam CMS anda untuk memanggil laluan API ini setiap kali kandungan diterbitkan atau dikemas kini. Ini memberikan anda kemas kini yang segera dan boleh dijangka.

5. Had 'Edge Runtime'

Anda melancarkan 'Middleware' Next.js atau laluan API ke 'Edge Runtime' untuk kelajuan, tetapi ia gagal dengan ralat yang sukar difahami.

• Masalah: Vercel Edge Runtime bukanlah persekitaran Node.js yang lengkap. Ia adalah 'V8 isolate' yang ringan. Jika kod anda atau salah satu kebergantungannya (dependency) cuba menggunakan API khusus Node.js (seperti fs untuk akses sistem fail), ia akan gagal semasa 'runtime'. Kami pernah melihat ini berlaku dengan pakej untuk penjanaan PDF atau pemprosesan imej yang kompleks.
• Penyelesaian: Semak kebergantungan anda untuk penggunaan API Node.js. Pilihan anda ialah:
  • Cari pakej alternatif yang serasi dengan 'Edge'.
  • Pindahkan logik yang memerlukan API Node.js ke 'Serverless Function' biasa, yang berjalan dalam persekitaran Node.js yang lengkap.

Kegagalan Lazim Lain yang Pernah Kami Baiki

Berikut adalah beberapa lagi isu ringkas yang telah kami bantu pasukan di Malaysia selesaikan:

• Ralat 'Path' Sensitif Huruf: Komponen diimport sebagai import from '../components/Header' tetapi nama failnya ialah header.js. Ini berfungsi pada sistem yang tidak sensitif huruf seperti Windows atau macOS tetapi gagal pada pelayan binaan Vercel yang berasaskan Linux. Penyelesaian: Pastikan semua laluan 'import' sepadan dengan nama fail dan folder, termasuk penggunaan huruf besar dan kecil.
• 'Build Timeout': Laman e-dagang yang besar dengan ribuan produk yang dijana sebagai halaman statik melebihi had masa binaan (cth., 45 minit pada pelan Pro). Penyelesaian: Optimumkan proses binaan anda. Bolehkah sebahagian data diambil semasa 'runtime'? Bolehkah pemprosesan imej dioptimumkan? Jika tidak, anda mungkin perlu menghubungi sokongan Vercel untuk memohon lanjutan masa binaan.
• Ketiadaan engines dalam package.json: Kod anda menggunakan ciri dari Node.js 18, tetapi persekitaran binaan Vercel masih menggunakan Node.js 16. Penyelesaian: Nyatakan versi Node.js yang diperlukan dalam package.json anda: "engines": { "node": "18.x" }.
• 'Timeout' Fungsi Tanpa Pelayan (Serverless Function): Laluan API yang menjana laporan atau memproses pembayaran mengambil masa lebih lama daripada had pelaksanaan (cth., 10-15 saat pada pelan Pro). Penyelesaian: Rombak fungsi tersebut agar lebih pantas. Untuk tugasan yang lama, amalan terbaik adalah dengan membuat fungsi tersebut memulangkan respons segera dan menyerahkan kerja sebenar kepada perkhidmatan tugas latar belakang seperti 'message queue' (cth., AWS SQS).

Kesimpulan: Pendekatan Sistematik untuk 'Debugging'

Memperbaiki kegagalan 'deploy' Vercel selalunya berkisar tentang memahami persekitaran dan konfigurasi platform, bukan hanya kod itu sendiri. Sentiasa mulakan dengan log 'deployment'. Bacanya dengan teliti dari atas ke bawah. Jika 'build' berjaya tetapi aplikasi mempunyai ralat, semak log 'Runtime' untuk fungsi anda.

Dengan memahami masalah-masalah lazim ini, anda boleh menjimatkan masa dan mengelakkan kekecewaan. Di JRV Systems, kami pakar dalam membina 'pipeline' CI/CD yang mantap dan menyelesaikan masalah seperti ini untuk para pelanggan kami, memastikan sistem mereka sentiasa andal dan mudah diselenggara.