Kegagalan Deploy Vercel: Cara Betulkan 6 Isu Paling Kerap Berlaku

Vercel telah mengubah cara kita melancarkan aplikasi web moden, terutamanya untuk 'framework' seperti Next.js. Kelajuan dan kesenangaannya sukar ditandingi. Namun, seperti mana-mana platform, proses 'deployment' boleh gagal. Apabila ini berlaku, log yang dipaparkan boleh jadi mengelirukan dan membuang masa berjam-jam.

Di JRV Systems, kami membina dan menguruskan sistem untuk perniagaan di Malaysia menggunakan Vercel. Sepanjang tahun lepas, kami telah menyahpepijat (debug) ratusan isu 'deployment'. Kami perhatikan ada corak kesilapan lazim yang sering dihadapi oleh pasukan pembangun perisian. Artikel ini berkongsi isu-isu yang paling kerap berlaku dan cara penyelesaiannya.

Isu Lazim Kegagalan Deploy Vercel dan Cara Betulkannya

Mencari cara betulkan kegagalan 'deploy' Vercel selalunya bermula dengan memahami masalah-masalah umum. Ia jarang sekali berpunca daripada Vercel sendiri, tetapi lebih kepada perbezaan kecil antara mesin tempatan anda dan persekitaran 'build' Vercel. Berikut adalah enam isu utama yang kami sering temui.

1. Perbezaan 'Environment Variable'

Ini adalah punca kegagalan 'deployment' yang paling biasa. Sesuatu pembolehubah (variable) wujud dalam fail .env.local anda, tetapi tidak pernah ditambah ke dalam tetapan projek Vercel untuk persekitaran Production, Preview, atau Development.

• Masalah: Kod anda cuba mengakses process.env.API_KEY, tetapi nilainya undefined dalam kontena 'build' Vercel. Skrip 'build' kemudiannya gagal. Ini sering berlaku semasa integrasi dengan gerbang pembayaran Malaysia seperti Billplz atau SenangPay, di mana kunci API berbeza antara 'staging' dan 'production'.
• Penyelesaian: Semak semula 'environment variable' anda di papan pemuka projek Vercel di bawah Settings > Environment Variables. Pastikan setiap pembolehubah yang diperlukan oleh aplikasi anda telah ditetapkan untuk persekitaran yang betul (Production, Preview, Development). Jangan sekali-kali 'commit' fail .env.local ke Git; gunakan papan pemuka Vercel sebagai sumber rujukan utama.

2. Sensitiviti Huruf (Case Sensitivity) pada Nama Fail

Ini adalah isu klasik "ia berfungsi di mesin saya". Ramai pembangun perisian di Malaysia menggunakan Windows atau macOS, yang secara lalai mempunyai sistem fail yang tidak sensitif kepada huruf besar atau kecil. Persekitaran 'build' Vercel pula berjalan di atas Linux, yang sensitif kepada huruf.

• Masalah: Anda mengimport komponen seperti import MyButton from '../components/button'. Nama fail sebenar ialah Button.js. Kod ini berfungsi pada Mac anda, tetapi 'build' di Vercel gagal dengan ralat Module not found kerana ia tidak dapat mencari button.js.
• Penyelesaian: Tetapkan konvensyen penamaan yang ketat untuk semua fail dan folder (contohnya, PascalCase untuk komponen, kebab-case untuk halaman). Gunakan 'linter' seperti ESLint dengan peraturan yang boleh mengesan ralat laluan fail yang sensitif huruf. Sentiasa semak semula penyata import anda agar sepadan dengan ejaan dan penggunaan huruf besar/kecil nama fail yang sebenar.

3. Tetapan 'Build' atau Pengesanan 'Framework' yang Salah

Vercel sangat baik dalam mengesan 'framework' dan tetapan anda secara automatik. Walau bagaimanapun, dalam persediaan yang tidak standard seperti 'monorepo' (menggunakan Turborepo atau Nx), ia boleh terkeliru.

• Masalah: Vercel cuba menjalankan npm run build di direktori utama, tetapi aplikasi Next.js anda berada di sub-direktori seperti apps/web. Proses 'build' gagal kerana ia tidak dapat mencari package.json dengan skrip 'build' yang betul di direktori utama.
• Penyelesaian: Ganti tetapan 'build' secara manual di papan pemuka projek Vercel anda. Pergi ke Settings > General dan tetapkan yang berikut:
  • Build Command: cd apps/web && npm run build (atau arahan spesifik anda)
  • Output Directory: apps/web/.next (atau output yang betul untuk 'framework' anda)
  • Root Directory: Tetapkan ini kepada sub-direktori aplikasi yang ingin anda 'deploy', seperti apps/web.

4. Had Masa Serverless Function

Ini bukan kegagalan 'build', tetapi kegagalan 'runtime' yang sama mengganggu. Laman web anda berjaya di-'deploy', tetapi laluan API atau halaman 'server-side rendering' mengembalikan ralat 504 Gateway Timeout.

• Masalah: Sesuatu Serverless Function mengambil masa lebih lama untuk dilaksanakan daripada had yang dibenarkan. Pada pelan Hobby Vercel, hadnya ialah 10 saat; pada pelan Pro, ia 60 saat. Ini sering berlaku apabila memanggil API luaran yang perlahan (cth., pangkalan data kerajaan yang lama) atau melakukan pengiraan berat.
• Penyelesaian: Pertama, semak log fungsi anda di papan pemuka Vercel untuk mengesahkan puncanya adalah had masa. Kemudian, optimumkan fungsi anda. Bolehkah anda menyimpan 'cache' respons API luaran? Bolehkah pengiraan berat dipindahkan ke proses latar belakang atau dipecahkan kepada langkah-langkah yang lebih kecil? Jika tugas itu sememangnya memakan masa, pertimbangkan untuk memindahkannya ke perkhidmatan khas seperti 'message queue' atau platform pengehosan lain yang direka untuk proses yang panjang.

5. Isu 'Caching' dengan Incremental Static Regeneration (ISR)

ISR adalah ciri hebat dalam Next.js, tetapi kelakuan 'caching'nya boleh mengelirukan. Pasukan sering melaporkan bahawa kandungan mereka tidak dikemas kini selepas 'deploy'.

• Masalah: Anda telah menetapkan masa revalidate selama 60 saat pada satu halaman, tetapi kandungan tetap lapuk untuk tempoh yang lebih lama. Ini mungkin disebabkan oleh 'header' Cache-Control yang salah konfigurasi dari API backend anda atau lapisan 'caching' Vercel sendiri.
• Penyelesaian: Pastikan CMS atau API anda tidak menghantar 'header' Cache-Control yang agresif yang mengatasi logik revalidate Vercel. Untuk 'on-demand revalidation', pastikan anda melaksanakan fungsi revalidatePath atau revalidateTag dengan betul menggunakan token rahsia yang dikonfigurasikan sebagai 'environment variable'.

6. Fail Kunci Dependensi (Lock File) yang Lapuk

Fail seperti package-lock.json atau yarn.lock memastikan versi dependensi yang sama dipasang di mana-mana. Apabila ia tiada atau tidak selari, Vercel mungkin memasang versi pakej yang lebih baru dan rosak.

• Masalah: Kemas kini kecil pada pakej memperkenalkan perubahan yang menyebabkan kerosakan. Mesin tempatan anda mempunyai versi lama yang berfungsi, tetapi oleh kerana fail kunci anda tidak dikemas kini, proses 'build' Vercel memasang versi baru yang rosak. 'Build' gagal dengan ralat yang sukar difahami dari dalam node_modules.
• Penyelesaian: Sentiasa 'commit' fail package-lock.json atau yarn.lock anda ke repositori Git. Sebelum 'push' kod, jalankan npm install atau yarn install untuk memastikan fail kunci anda selari dengan package.json.

Pendekatan Sistematik untuk Menyahpepijat

Apabila 'deployment' Vercel gagal, jangan panik. Baca log 'build' dengan teliti, dari atas ke bawah. Ralatnya hampir selalu ada di situ, walaupun tidak begitu jelas pada mulanya. Dengan memahami isu-isu lazim ini, anda boleh mendiagnosis masalah dengan cepat dan menggunakan cara betulkan kegagalan 'deploy' Vercel yang betul, membolehkan projek anda kembali dalam talian dengan lebih pantas.