Panduan Konfigurasi Versi Node.js Bebas untuk Projek dengan ServBay (macOS)

ServBay ialah persekitaran pembangunan web tempatan yang berkuasa dan direka untuk pembangun, menawarkan penyelesaian sehenti yang mengintegrasikan pelbagai bahasa pengaturcaraan (termasuk Node.js), pangkalan data, dan pelayan web. Salah satu kelebihan utama ServBay ialah sokongan asli dan pengurusan fleksibel untuk berbilang versi Node.js. Dengan hanya satu fail konfigurasi mudah, anda boleh menentukan versi Node.js yang diperlukan untuk setiap projek tanpa bergantung pada pengurus versi luaran seperti NVM, fnm, atau Docker, sekaligus memudahkan aliran kerja anda serta mengelakkan pencemaran dan konflik persekitaran global.

Dokumen ini akan menerangkan secara terperinci cara menggunakan fail .servbay.config ServBay untuk mengawal versi Node.js per projek.

Kenapa Pilih .servbay.config ServBay untuk Pengurusan Versi Node.js?

Kaedah pengurusan versi Node.js tradisional seperti menggunakan NVM atau pemasangan manual sering menimbulkan beberapa masalah:

• Pencemaran dan Konflik Global: Memasang Node.js secara global atau menukar versi secara global dengan pengurus versi mudah menyebabkan kebergantungan projek bercanggah antara satu sama lain.
• Masa Pemasangan dan Kompilasi: Memasang versi baru atau bertukar arkitektur (seperti x86_64 dan arm64) mungkin memerlukan kompilasi semula modul, yang memakan masa dan kompleks.
• Beban Docker: Untuk keperluan hanya versi Node.js tertentu, menggunakan kontena Docker penuh boleh jadi berat dan tidak efisien.

ServBay mengatasi masalah ini dengan pra-pemasangan pelbagai versi Node.js utama yang popular (kini menyokong v12 hingga v23, semua sub-versi utama dan minor — rujuk seksyen "Pakej" dalam aplikasi ServBay untuk lihat dan urus versi), dan memanfaatkan fail .servbay.config untuk menawarkan penyelesaian yang lebih elegan:

• Pertukaran Serta-merta: Versi sudah siap dipasang, penukaran adalah hampir serta-merta.
• Pengasingan Projek: Konfigurasi hanya sah dalam direktori projek, memastikan pengasingan versi tahap projek sebenar.
• Tiada Pencemaran Global: Tidak mengubah tetapan global sistem, sistem tetap bersih.
• Integrasi dengan ServBay: Berfungsi lancar dalam persekitaran pembangunan ServBay dan bersama dengan pakej lain yang diurus (seperti PHP, pangkalan data, pelayan web, dsb).

Prasyarat

Sebelum memulakan, pastikan:

1. ServBay telah dipasang dan dijalankan dengan baik pada macOS anda.
2. Versi Node.js yang diperlukan untuk projek anda telah diaktifkan melalui antara muka aplikasi ServBay dalam senarai “Pakej” (“Packages”).
3. Anda mempunyai direktori projek yang memerlukan konfigurasi Node.js khusus.

Prinsip Teras

ServBay akan memantau direktori semasa dalam persekitaran terminal terbina dalamnya. Bila anda menggunakan arahan cd untuk masuk ke direktori tertentu, ServBay akan mencari ke atas dari direktori semasa dan semua direktori induk untuk fail bernama .servbay.config. Setelah dijumpai (akan menggunakan yang paling hampir dengan direktori semasa), ServBay akan membaca tetapan di dalam fail ini, kemudian melaraskan pembolehubah persekitaran terminal secara dinamik — contohnya mengubah PATH supaya menunjuk ke laluan pemasangan Node.js yang tertentu seperti yang ditentukan dalam .servbay.config.

Dengan mekanisme ini, setiap sesi terminal dalam direktori projek boleh memuatkan dan menggunakan versi Node.js masing-masing secara automatik, tanpa perlu tukar secara manual.

Langkah Konfigurasi

Untuk mengkonfigurasi versi Node.js yang berbeza untuk setiap projek, anda hanya perlukan dua langkah mudah:

Langkah 1: Cipta dan Sunting Fail .servbay.config

Di direktori akar projek anda (biasanya yang mengandungi fail package.json), cipta satu fail baru bernama .servbay.config.

Buka fail tersebut menggunakan editor teks kegemaran anda, kemudian tambah kandungan seperti berikut:

# Tentukan nombor versi utama Node.js untuk projek ini
# ServBay akan secara automatik memilih versi terbaru di bawah versi utama ini yang telah dipasang
NODE_VERSION=20

# Pilihan: Tetapkan mirror npm atau pnpm untuk mempercepat pemasangan kebergantungan
# Jika anda di China Daratan, digalakkan gunakan mirror tempatan
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Pilihan: Tetapkan direktori cache npm atau pnpm
# Disarankan untuk menggunakan direktori sementara ServBay supaya cache tidak bertebaran dalam sistem
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Penjelasan Konfigurasi:

• NODE_VERSION: Wajib. Tentukan nombor versi utama Node.js yang diperlukan projek. Contohnya, set 20 bermaksud gunakan versi terbaru dalam siri Node.js 20.x yang telah dipasang melalui ServBay. Pastikan versi tersebut telah dipasang.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Pilihan. Tetapan alamat mirror untuk Yarn atau npm. Berguna untuk mempercepat pemasangan kebergantungan terutamanya jika rangkaian lemah.
• NPM_CONFIG_CACHE: Pilihan. Direktori cache npm atau pnpm. Letakkannya di direktori sementara ServBay (/Applications/ServBay/tmp/npm/cache) membantu pengurusan cache yang lebih baik dan elakkan pencemaran direktori pengguna.

Simpan dan tutup fail .servbay.config.

Langkah 2: Sahkan Versi dalam Terminal ServBay

1. Buka antara muka utama aplikasi ServBay.

2. Klik butang “Terminal” untuk melancarkan terminal terbina dalam ServBay.

3. Dalam terminal, gunakan arahan cd untuk ke direktori projek anda.

   cd /Applications/ServBay/www/your-project-name

   (Sila tukarkan /Applications/ServBay/www/your-project-name kepada laluan sebenar projek anda)

4. Jalankan arahan node -v untuk periksa versi Node.js yang sedang aktif.

   node -v

   Paparan sepatutnya menunjukkan versi yang anda tetapkan dalam .servbay.config (contohnya v20.x.x).

5. Anda juga boleh menjalankan npm -v (atau pnpm -v, yarn -v) untuk memastikan pengurus pakej turut berkaitan dengan versi Node.js semasa.

Kini, setiap kali anda menjalankan sebarang arahan Node.js atau npm/pnpm/yarn dalam direktori projek ini, versi Node.js dan pengurus pakej yang akan digunakan adalah seperti yang dinyatakan dalam .servbay.config.

Contoh Pelaksanaan

Di bawah ialah contoh ringkas menunjukkan bagaimana .servbay.config memungkinkan penukaran automatik versi Node.js antara projek yang berbeza.

Andaikan anda mempunyai dua projek: project-a memerlukan Node.js v18 manakala project-b memerlukan Node.js v20.

1. Cipta direktori projek dan fail konfigurasi:

   # Cipta direktori contoh projek dalam direktori www ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Untuk project-a, cipta .servbay.config dan tetapkan Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Untuk project-b, cipta .servbay.config dan tetapkan Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Sahkan pertukaran versi melalui terminal ServBay:

   Buka terminal ServBay dan jalankan perintah berikut:

   # Masuk ke direktori project-a
   cd /Applications/ServBay/www/project-a
   # Periksa versi Node.js
   node -v
   # Dijangka: v18.x.x
   
   # Masuk ke direktori project-b
   cd ../project-b
   # Periksa versi Node.js
   node -v
   # Dijangka: v20.x.x
   
   # Kembali ke direktori project-a
   cd ../project-a
   # Periksa versi Node.js
   node -v
   # Dijangka: v18.x.x

Melalui contoh ini, anda dapat lihat bahawa ServBay secara automatik memuat dan menggunakan konfigurasi NODE_VERSION daripada fail .servbay.config projek berdasarkan direktori semasa — tanpa perlu pertukaran manual versi Node.js.

Gambar di bawah menunjukkan bagaimana versi Node.js akan berubah secara automatik mengikut .servbay.config apabila bertukar direktori projek (imej hanya untuk rujukan, antara muka sebenar mungkin berbeza):

Perhatian

• Fail .servbay.config mesti diletakkan dalam direktori projek atau mana-mana induknya. ServBay akan mencari ke atas dan hanya menggunakan fail pertama yang dijumpai (paling hampir).
• Pastikan anda bekerja dalam terminal terbina dalam ServBay, atau gunakan persekitaran terminal luaran yang telah dikonfigurasi dengan pembolehubah persekitaran ServBay.
• Versi NODE_VERSION yang dinyatakan mesti telah dipasang dan diaktifkan dalam aplikasi ServBay. Jika tidak, ServBay mungkin akan menggunakan versi lalai atau tidak dapat menemui Node.js.
• Konfigurasi dalam .servbay.config hanya memberi kesan ke sesi terminal semasa dan subprocess-nya, tidak akan mempengaruhi sistem global atau proses lain di luar persekitaran ServBay.

Soal Jawab Lazim (FAQ)

S: Apa berlaku jika direktori projek saya tiada fail .servbay.config?

J: Jika ServBay tidak menemui fail .servbay.config di direktori semasa atau mana-mana direktori induk, ia akan menggunakan konfigurasi global atau versi Node.js lalai dalam ServBay (kebiasaannya versi yang ditandakan "default").

S: Bagaimana saya tahu versi Node.js mana yang disokong oleh ServBay?

J: Buka aplikasi ServBay, pergi ke bahagian “Pakej” di menu kiri. Di sana anda boleh melihat senarai semua pakej yang tersedia dan telah dipasang, termasuk versi Node.js yang berbeza. Anda boleh tandakan atau nyah-tanda untuk mengaktifkan atau menyahaktifkan versi tertentu.

S: Adakah konfigurasi dalam .servbay.config mempengaruhi seluruh sistem saya?

J: Tidak. Semua konfigurasi dalam .servbay.config adalah sementara dan hanya berkesan di sesi terminal ServBay semasa atau proses yang menggunakan pembolehubah persekitaran ServBay. Ia tidak mengubah pembolehubah persekitaran global sistem anda atau menjejaskan program yang berjalan di luar persekitaran ServBay. Inilah kunci pengasingan projek oleh ServBay.

S: Selain NODE_VERSION, adakah tetapan lain boleh dikonfigurasi dalam .servbay.config?

J: Ya, fail .servbay.config ialah mekanisme umum untuk konfigurasi pembolehubah persekitaran tahap projek oleh ServBay. Selain tetapan berkaitan Node.js, anda juga boleh menetapkan pembolehubah lain yang diperlukan untuk projek. Item yang disokong mungkin bertambah dengan versi ServBay yang baru, tetapi asas utamanya adalah tetapan pembolehubah persekitaran.

Rumusan

Dengan memanfaatkan fail .servbay.config ServBay, anda boleh menentukan dan mengurus versi Node.js yang berbeza untuk setiap projek pembangunan tempatan dengan mudah dan efisien. Kaedah ini jauh lebih ringan dan mudah berbanding pengurus versi tradisional atau penyelesaian kontena, serta menyatu sempurna ke dalam persekitaran pembangunan bersepadu ServBay — membantu anda membina aliran kerja yang lebih stabil dan kolaboratif. Mulakan penggunaan .servbay.config dalam projek anda sekarang dan alami kemudahan luar biasa yang ditawarkan oleh ServBay!