Cara Mengganti Versi Node.js di Panel Pterodactyl lewat Docker Image

Aplikasi Node.js yang tadinya jalan tiba-tiba error setelah diperbarui, atau script baru yang kamu pasang langsung crash. Penyebab yang sangat sering: versi Node.js di servermu tidak cocok dengan kebutuhan project. Versi itu diatur lewat Docker Image di tab Startup, dan mengubahnya hanya butuh beberapa menit.

Apa itu Docker Image

Server di panel berjalan di dalam "kotak" terisolasi. Docker Image adalah paket isi kotak itu, termasuk program yang dipakai untuk menjalankan aplikasimu. Untuk egg Node.js, pilihan Docker Image-nya adalah versi Node.js, misalnya Nodejs 18, Nodejs 20, atau Nodejs 24. Mengganti Docker Image berarti mengganti versi Node.js yang dipakai servermu.

Kapan kamu perlu menggantinya

• Di Console muncul tulisan seperti requires Node.js 20+ atau You are using Node.js 18.
• Log pemasangan paket menyebut Unsupported engine atau EBADENGINE.
• Muncul error Cannot find module atau Cannot find package tepat setelah script diperbarui. Lihat Mengatasi error "Cannot find module".
• Muncul SyntaxError pada kode yang kelihatan benar. Biasanya fitur bahasa baru dipakai di Node.js versi lama.
• Project lama error di Node.js versi terbaru (lihat bagian "Terlalu baru juga bisa bermasalah").

Cara mengetahui versi yang dipakai sekarang

• Buka tab Startup. Versi yang sedang aktif terlihat di bagian Docker Image.
• Atau lihat baris Node.js v... di bagian bawah pesan error di Console, misalnya Node.js v18.20.8.

Cara menentukan versi yang dibutuhkan

Cek berurutan sampai ketemu:

1. Pesan error di Console, misalnya "requires Node.js 20+".
2. File package.json, bagian "engines", misalnya "node": ">=20".
3. README atau dokumentasi script dari pembuatnya.

Kalau tidak ada petunjuk sama sekali, hubungi pemilik/pembuat sc nya untuk menanyakan versi nodejs nya (jika kamu menggunakan script shared) atau pilih versi genap yang cukup baru (18, 20, 22, 24). Versi genap adalah versi LTS yang jangka dukungnya panjang, sedangkan versi ganjil (19, 21, 23, 25) berumur pendek.

Langkah mengganti Docker Image

1. Buka tab Console, lalu klik Stop sampai server berstatus Offline.
2. Buka tab Startup, lalu cari bagian Docker Image.
3. Pilih versi Node.js yang kamu butuhkan dari daftar. Perubahannya tersimpan otomatis.
4. Buka tab Files. Kalau ada folder node_modules, hapus folder itu supaya modul terpasang ulang dengan versi yang benar. Jangan hapus file package.json.
5. Buka tab Console, lalu klik Start. Panel memasang ulang modul secara otomatis, jadi tunggu sampai prosesnya selesai.

Setelah menyala, kamu bisa memastikan versinya lewat log. Kalau ada error baru, baris Node.js v... di bagian bawah error menunjukkan versi yang sekarang dipakai.

Terlalu baru juga bisa bermasalah

Versi terbaru tidak otomatis lebih baik. Project lama dan beberapa modul yang berisi kode bawaan (misalnya yang memakai node-gyp) bisa gagal dipasang di Node.js yang terlalu baru. Kalau error muncul setelah menaikkan versi, coba turun ke versi di bawahnya yang masih memenuhi kebutuhan project.

Kalau error masih muncul

Berlaku juga untuk egg lain

Menu Docker Image juga ada di egg lain. Di egg Python ia menentukan versi Python, dan di egg Minecraft ia menentukan versi Java. Software yang butuh Java versi tertentu akan error kalau Docker Image-nya tidak cocok, jadi caranya sama: baca kebutuhan versinya, lalu pilih image yang sesuai.

Pada server website Next.js, mengganti Docker Image lalu menekan Start berarti install dan build berjalan ulang. Itu normal dan butuh beberapa menit. Lihat Cara hosting website Next.js.

Langkah lanjutan

Kalau setelah ganti versi masih bermasalah, ikuti panduan lengkap di Cara mengatasi error Node.js di Pterodactyl. Penjelasan semua variabel Startup ada di Startup dan variabel.