Cara Betulkan Kegagalan Deploy Vercel: Isu Lazim Pasukan Malaysia

Vercel menawarkan pengalaman 'deployment' yang lancar, tetapi apabila berlaku masalah, log ralatnya boleh jadi sukar difahami. Di JRV Systems, kami membina dan menguruskan sistem untuk perniagaan di Malaysia, dan kami telah meluangkan banyak masa menyahpepijat 'pipeline' Vercel.

Artikel ini berkongsi kegagalan 'deploy' Vercel yang paling kerap kami temui dan cara praktikal kami menyelesaikannya. Ini bukan teori semata-mata; ia berdasarkan pengalaman langsung kami membantu pasukan pembangun tempatan melancarkan produk mereka.

Cara Lazim Betulkan Kegagalan Deploy Vercel: Pembolehubah Persekitaran

Ini merupakan punca utama kegagalan 'deployment'. Masalahnya hampir selalu berpunca daripada ketidakpadanan antara fail .env tempatan pembangun dan pembolehubah yang dikonfigurasikan dalam tetapan projek Vercel. Sama ada pembolehubah tersebut tiada, mempunyai nilai yang berbeza, atau tidak ditetapkan kepada persekitaran yang betul (Production, Preview, atau Development).

Satu contoh klasik yang kami pernah selesaikan melibatkan 'connection string' pangkalan data. Ia berfungsi dengan baik di persekitaran tempatan, tetapi pembolehubah DATABASE_URL tidak pernah ditambah ke persekitaran Production di papan pemuka Vercel. Proses 'build' berjalan lancar, tetapi aplikasi akan gagal berfungsi semasa 'runtime', memaparkan ralat 500 yang umum.

Penyelesaiannya:

• Standardkan: Simpan satu fail .env.example dalam repositori anda yang menyenaraikan semua kunci pembolehubah yang diperlukan, tetapi tanpa nilai rahsia.
• Audit: Sebelum 'deployment' besar, audit semua pembolehubah di Vercel dalam Project Settings > Environment Variables. Pastikan ia ditetapkan untuk persekitaran yang betul.
• Automasi (Lanjutan): Untuk pasukan yang lebih besar, guna Vercel CLI atau servis seperti Doppler untuk menyelaraskan pembolehubah dan mengelakkan kesilapan manual.

Emel 'Author' Git Tidak Sepadan Dalam Skop Pasukan

Masalah ini khusus untuk akaun pasukan dan boleh mengelirukan: Author of this commit is not a member of the Team. Model keselamatan Vercel memerlukan alamat emel yang digunakan untuk membuat 'commit' Git mestilah dikaitkan dengan akaun pengguna dalam pasukan Vercel tersebut.

Kami melihat ini berlaku dengan seorang klien yang mengupah pembangun bebas. Pembangun tersebut menggunakan emel peribadinya ([email protected]) untuk 'commit' Git, tetapi jemputan Vercel dihantar ke emel kerjanya ([email protected]). Setiap 'push' yang dibuat mencetuskan kegagalan 'deployment'.

Penyelesaiannya: Pembangun tersebut perlu sama ada:

1. Menambah emel 'commit' beliau ([email protected]) sebagai emel kedua dalam akaun Vercel.
2. Mengubah konfigurasi Git tempatan untuk menggunakan alamat emel yang dikaitkan dengan akaun Vercel (git config user.email "[email protected]").

Pengesanan 'Framework' dan Arahan 'Build' Khas

Pengesanan 'framework' automatik Vercel sangat baik untuk struktur projek standard. Walau bagaimanapun, ia sering gagal dalam tetapan 'monorepo' (seperti yang menggunakan Turborepo atau Nx) atau dengan susun atur projek yang tidak standard. Vercel mungkin mengesan package.json di direktori utama tetapi tidak tahu di mana letaknya aplikasi web sebenar.

Untuk satu projek e-dagang baru-baru ini yang dibina di atas Turborepo, Vercel terus cuba menjalankan npm run build di direktori utama, sedangkan itu bukan arahan yang betul. Aplikasi Next.js sebenar terletak di dalam apps/web.

Penyelesaiannya: Konfigurasi tetapan 'build' secara manual dalam Project Settings > General di Vercel:

• Framework Preset: Tetapkan kepada 'framework' anda (cth., Next.js).
• Build Command: Ganti dengan cd apps/web && npm run build.
• Output Directory: Tetapkan ke laluan yang betul, seperti apps/web/.next.
• Install Command: Pastikan ia memasang 'dependencies' dari direktori utama, cth., npm install.

Memahami Had Fungsi Edge dan Serverless

Pilihan antara 'runtime' Edge dan Serverless di Vercel mempunyai implikasi yang besar. Kami sering melihat pasukan mencari penyelesaian untuk kegagalan 'deploy' Vercel yang melibatkan pemindahan logik dari satu 'runtime' ke 'runtime' yang lain. Fungsi Edge pantas dan diedarkan secara global tetapi mempunyai had yang ketat:

• Saiz: Ia mempunyai had saiz 'bundle' yang kecil (biasanya di bawah 1 MB).
• API: Ia tidak menyokong semua API Node.js, terutamanya yang berinteraksi dengan sistem fail atau modul OS natif.

Satu pasukan cuba menggunakan 'library' sharp untuk pemprosesan imej dalam API route Next.js yang dikonfigurasikan untuk 'runtime' Edge. 'Deployment' gagal kerana sharp bergantung pada 'native binaries' yang tidak serasi dengan persekitaran Edge.

Penyelesaiannya: Analisa 'dependencies' anda. Jika sesuatu fungsi memerlukan 'library' yang berat atau API Node.js tertentu, pastikan ia di-'deploy' sebagai Serverless Function. Pindahkan tugas pengkomputeran yang intensif ke Serverless Function yang khusus dan pastikan Edge Function sentiasa ringkas untuk tugas seperti pengesahan, 'redirect', atau pengambilan data yang mudah.

Isu 'Cache' Incremental Static Regeneration (ISR)

ISR adalah ciri Next.js yang hebat, tetapi ia boleh menyebabkan kegagalan yang tidak ketara. Isu biasa ialah kegagalan 'build' kerana sumber data yang diperlukan oleh getStaticProps tidak tersedia buat sementara waktu semasa 'deployment'. Proses 'build' cuba untuk pra-jana halaman, gagal mendapatkan data, dan keseluruhan 'deployment' terhenti.

Satu lagi masalah ialah "cache poisoning," di mana ralat semasa proses 'revalidation' menyebabkan versi halaman yang rosak disimpan dalam 'cache' dan dihidangkan kepada semua pengguna sehingga 'revalidation' seterusnya berjaya.

Penyelesaiannya:

• Pengambilan Data yang Kukuh: Gunakan blok try...catch untuk panggilan pengambilan data dalam getStaticProps. Jika pengambilan gagal semasa 'build' awal, anda boleh memilih sama ada untuk menggagalkan 'build' secara sengaja atau mengembalikan 'props' sandaran untuk memaparkan halaman yang tidak rosak.
• On-Demand Revalidation: Untuk data kritikal yang berubah tanpa dijangka, utamakan 'On-Demand Revalidation'. Ini membolehkan anda mencetuskan 'rebuild' halaman melalui 'webhook' selamat (contohnya, dari CMS anda selepas kandungan baru diterbitkan) dan bukannya bergantung pada selang masa. Ini memberi anda lebih banyak kawalan dan mengurangkan risiko menyimpan data yang lapuk atau salah dalam 'cache'.

Dengan memahami masalah-masalah lazim ini, pasukan anda boleh mengurangkan masa untuk menyelesaikan masalah 'deployment' dan lebih fokus pada pembinaan ciri-ciri baharu. Kuncinya adalah pendekatan yang berdisiplin terhadap konfigurasi, pemahaman yang jelas tentang proses 'build' Vercel, dan pengendalian ralat yang proaktif dalam kod aplikasi anda.