Cara Betulkan Kegagalan Deploy Vercel: Panduan Untuk Pasukan di Malaysia

Di JRV Systems, kami banyak menggunakan Vercel untuk deploy aplikasi web bagi klien kami di seluruh Malaysia. Ia platform yang hebat, tetapi proses deployment boleh gagal atas sebab-sebab yang tidak begitu jelas. Build yang gagal akan membazir masa dan boleh menyekat kemas kini penting untuk laman e-dagang atau dashboard dalaman.

Artikel ini menghuraikan beberapa kegagalan deploy Vercel yang biasa kami temui dan menyediakan panduan praktikal untuk setiap cara betulkan kegagalan deploy Vercel. Ini adalah isu-isu sebenar yang telah kami selesaikan untuk pasukan di Seremban, KL, dan lokasi lain.

Kegagalan Deploy Vercel yang Biasa & Cara Memperbaikinya

Kebanyakan ralat deployment tergolong dalam beberapa kategori utama. Log ralat di dashboard Vercel adalah tempat pertama untuk menyemak, tetapi mesej yang dipaparkan kadangkala boleh mengelirukan. Berikut adalah perkara yang perlu diperhatikan berdasarkan pengalaman kami.

1. Percanggahan Environment Variable

Ini adalah isu yang paling kerap berlaku. Pembangun perisian menggunakan fail .env.local pada mesin mereka, yang sememangnya tidak dimasukkan ke dalam Git. Masalah timbul apabila variable baharu ditambah secara lokal tetapi tidak dikemas kini dalam tetapan projek di Vercel.

• Simptom: Build gagal dengan ralat seperti TypeError: Cannot read properties of undefined atau klien API tertentu melaporkan 'key' yang hilang. Aplikasi berfungsi dengan sempurna pada komputer anda.
• Penyelesaian: Pergi ke Projek Vercel anda > Settings > Environment Variables. Bandingkan satu per satu variable di sana dengan fail .env.local anda. Pastikan semua variable yang diperlukan wujud untuk persekitaran Preview dan Production. Amalan yang baik adalah untuk menyediakan fail templat seperti .env.example dalam repositori anda untuk menjejak variable yang diperlukan.

2. Perbezaan Huruf Besar/Kecil (Case) dan Laluan Fail

Ramai pembangun di Malaysia menggunakan Windows atau macOS, yang sistem failnya secara lalai tidak sensitif kepada huruf besar/kecil (case-insensitive). Persekitaran build Vercel berjalan di atas Linux, yang bersifat case-sensitive. Perbezaan ini adalah punca klasik kegagalan build.

• Simptom: Build gagal dengan ralat Module not found: Can't resolve './components/header.js', walaupun fail tersebut wujud secara lokal sebagai Header.js dan berfungsi dengan baik.
• Penyelesaian: Tetapkan konvensyen penamaan yang konsisten untuk semua fail dan folder (cth., PascalCase untuk komponen, kebab-case untuk yang lain). Semak semula penyata import anda untuk memastikan penggunaan huruf besar/kecil adalah tepat sama dengan nama fail. Alat seperti ESLint boleh dikonfigurasi untuk memberi amaran tentang isu ini sebelum anda commit kod anda.

3. Ralat pada Build Command dan Direktori Output

Vercel sangat cekap dalam mengesan framework secara automatik seperti Next.js, SvelteKit, atau Astro. Namun, dalam monorepo atau projek dengan tetapan khas, pengesanan automatik ini boleh gagal.

• Simptom: Log build menunjukkan ralat seperti no such file or directory, open '/vercel/path0/dist/index.html' atau build selesai tetapi deployment memaparkan ralat 404.
• Penyelesaian: Gantikan tetapan build secara manual dalam projek Vercel anda. Pergi ke Project Settings > General dan cari bahagian Build & Development Settings.
  • Build Command: Tetapkan skrip build anda secara eksplisit, cth., npm run build atau pnpm -F my-app build untuk monorepo.
  • Output Directory: Nyatakan folder yang betul di mana framework anda meletakkan aset statik. Untuk Next.js, ia adalah .next; untuk Vite/SvelteKit, selalunya build atau dist.
  • Install Command: Pastikan Vercel menggunakan pengurus pakej yang betul (pnpm install, yarn install).

4. Pengguna Git Tidak Sepadan dengan Pasukan Vercel

Isu ini sering mengelirukan pembangun junior. Model keselamatan Vercel untuk akaun pasukan memerlukan individu yang membuat commit kod adalah ahli pasukan Vercel tersebut.

• Simptom: Deployment disekat dengan mesej seperti The Git user "John Doe" <john.doe@personal-email.com> is not a member of the Vercel team.
• Penyelesaian: Pembangun perlu mengkonfigurasi klien Git lokal mereka untuk menggunakan alamat e-mel yang dikaitkan dengan akaun Vercel mereka. Ini boleh dilakukan untuk repositori tertentu: git config user.name "Nama Anda" git config user.email "emel-kerja-anda@syarikat.com" Selepas menetapkan e-mel yang betul, mereka mesti meminda commit terakhir (git commit --amend --no-edit) dan melakukan force-push untuk mencetuskan deployment baharu.

5. Had Fungsi Serverless dan Edge

Kami membina banyak sistem dengan fungsi serverless untuk tugasan seperti pemprosesan pembayaran atau integrasi AI. Adalah penting untuk memahami hadnya di platform Vercel.

• Simptom: Build berjaya, tetapi fungsi gagal semasa runtime dengan ralat 500. Log fungsi mungkin menunjukkan Error: The Edge Function "api/my-function" is using "fs" which is not supported. atau 'timeout'.
• Penyelesaian: Ambil tahu tentang kekangan yang ada:
  • Edge Runtime: Tidak menyokong API Node.js natif seperti fs atau path. Anda mesti menggunakan API standard web. Ia direka untuk kelajuan dan mempunyai had pelaksanaan yang sangat singkat.
  • Serverless Functions: Mempunyai had saiz (50MB termampat) dan had memori. Pakej yang berat (seperti sesetengah library untuk menjana PDF) boleh melebihi had ini. Gunakan alat seperti bundle-analyzer untuk memeriksa saiz fungsi anda dan buang pakej yang tidak perlu.
  • Masa Pelaksanaan: Fungsi pada pelan Hobby akan 'timeout' selepas 10 saat. Untuk tugasan yang lebih lama, seperti memproses fail besar daripada pengguna di Malaysia dengan internet yang lebih perlahan, anda perlu menaik taraf pelan anda atau menstruktur semula tugasan tersebut supaya berjalan secara 'asynchronous', mungkin dengan menggunakan sistem giliran (queueing system).

Pendekatan Sistematik untuk Debugging

Apabila deployment gagal, jangan panik. Pendekatan yang teratur adalah cara betulkan kegagalan deploy Vercel yang paling pantas. Pertama, baca log build dengan teliti dari atas ke bawah. Kedua, cuba hasilkan semula ralat secara lokal dengan menjalankan arahan build yang sama seperti dalam package.json anda. Akhir sekali, semak halaman status Vercel untuk memastikan tiada isu di peringkat platform. Dengan memahami masalah-masalah umum ini, pasukan anda dapat menyelesaikan isu deployment dengan lebih cepat dan mengekalkan momentum pembangunan.