Hướng dẫn cấu hình Node.js riêng cho từng dự án với ServBay (macOS)

ServBay là một môi trường phát triển web mạnh mẽ được thiết kế dành riêng cho lập trình viên, cung cấp giải pháp một cửa tích hợp nhiều ngôn ngữ lập trình, cơ sở dữ liệu và máy chủ web, trong đó có Node.js. Một ưu điểm nổi bật của ServBay là khả năng hỗ trợ đa phiên bản Node.js và quản lý linh hoạt phiên bản. Thông qua một file cấu hình đơn giản, bạn có thể dễ dàng chỉ định phiên bản Node.js cần thiết cho mỗi dự án mà không cần phụ thuộc vào các trình quản lý phiên bản bên ngoài như NVM, fnm hay sử dụng container Docker, nhờ đó giúp quy trình làm việc trở nên đơn giản hơn và tránh xung đột phiên bản hoặc ô nhiễm môi trường toàn cục.

Bài viết này sẽ hướng dẫn chi tiết cách sử dụng file .servbay.config của ServBay để kiểm soát phiên bản Node.js ở cấp độ dự án.

Vì sao nên dùng .servbay.config của ServBay để quản lý phiên bản Node.js?

Các phương pháp quản lý Node.js truyền thống, như dùng NVM hoặc cài đặt thủ công, có thể gặp một số bất cập:

• Ô nhiễm và xung đột môi trường toàn cục: Cài đặt trực tiếp hoặc chuyển đổi các phiên bản Node.js trên hệ thống dễ dẫn đến xung đột phụ thuộc giữa các dự án khác nhau.
• Tốn thời gian cài đặt/biên dịch: Việc cài mới phiên bản hoặc chuyển đổi giữa các kiến trúc (như x86_64 và arm64) có thể yêu cầu biên dịch lại các module, vừa tốn thời gian vừa phức tạp.
• Chi phí sử dụng Docker: Đối với nhu cầu chỉ cần một phiên bản Node.js cụ thể, việc sử dụng container Docker là quá nặng nề.

ServBay mang lại giải pháp ưu việt nhờ đã cài sẵn nhiều phiên bản Node.js phổ biến (hiện hỗ trợ v12 đến v23 cho tất cả các phiên bản chính và phụ; bạn có thể xem và quản lý trong mục “Packages” của ứng dụng ServBay) kết hợp cùng file .servbay.config:

• Chuyển đổi tức thì: Phiên bản đã được cài sẵn, việc chuyển đổi diễn ra gần như tức thời.
• Cô lập dự án: Cấu hình chỉ áp dụng trong thư mục dự án, đảm bảo cô lập phiên bản ở từng dự án thực sự.
• Không ô nhiễm môi trường toàn cục: Không can thiệp vào môi trường hệ thống, giữ hệ thống luôn sạch sẽ.
• Tích hợp sâu với ServBay: Hoạt động liền mạch với môi trường phát triển của ServBay cũng như các phần mềm khác do ServBay quản lý (như PHP, cơ sở dữ liệu, máy chủ web, v.v.).

Điều kiện cần thiết

Trước khi bắt đầu, bạn cần:

1. Đã cài đặt và chạy thành công ServBay trên macOS.
2. Đã xác nhận và kích hoạt phiên bản Node.js cần thiết cho dự án thông qua giao diện “Packages” của ServBay.
3. Có một thư mục dự án muốn cấu hình phiên bản Node.js riêng.

Nguyên lý hoạt động

Khi bạn sử dụng môi trường terminal tích hợp của ServBay, ứng dụng sẽ theo dõi thư mục hiện tại. Khi bạn cd vào một thư mục, ServBay sẽ quét từ thư mục đó lên các thư mục cha để tìm file có tên .servbay.config. Khi tìm được (ưu tiên file nằm gần vị trí hiện tại nhất), ServBay sẽ đọc các tùy chọn trong file và điều chỉnh biến môi trường của session terminal tương ứng, ví dụ như chỉnh biến PATH trỏ về đường dẫn cài đặt phiên bản Node.js chỉ định trong .servbay.config.

Cơ chế này đảm bảo rằng các session terminal nằm ở các thư mục dự án khác nhau sẽ tự động nạp và sử dụng đúng phiên bản Node.js được chỉ định — không cần chuyển đổi thủ công.

Cách cấu hình

Việc cấu hình Node.js độc lập cho từng dự án chỉ gồm 2 bước đơn giản:

Bước 1: Tạo và chỉnh sửa file .servbay.config

Ở thư mục gốc dự án (thường chính là nơi chứa file package.json), hãy tạo một file mới tên .servbay.config.

Mở file này bằng trình soạn thảo yêu thích và thêm vào nội dung:

# Chỉ định phiên bản Node.js chính dự án cần dùng
# ServBay sẽ tự động chọn phiên bản mới nhất cùng dòng này đã được cài đặt
NODE_VERSION=20

# Tùy chọn: Cấu hình registry mirror cho npm hoặc pnpm để tăng tốc cài đặt gói phụ thuộc
# Nếu bạn ở Việt Nam hoặc cần tăng tốc, có thể chọn mirror phù hợp
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Tùy chọn: Chỉ định thư mục cache cho npm hoặc pnpm
# Khuyến nghị đặt trong thư mục tạm của ServBay để tránh chiếm dụng ổ đĩa hệ thống hoặc làm rối thư mục người dùng
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Giải thích các tùy chọn:

• NODE_VERSION: Bắt buộc. Chỉ định phiên bản Node.js chính cần dùng cho dự án. Ví dụ 20 nghĩa là sử dụng Node.js 20.x mới nhất đã cài trong ServBay. Đảm bảo phiên bản đó đã được cài thông qua ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Tùy chọn. Cấu hình địa chỉ mirror registry cho Yarn hoặc npm nhằm tăng tốc cài đặt package, nhất là khi đường truyền quốc tế không ổn định.
• NPM_CONFIG_CACHE: Tùy chọn. Chỉ định đường dẫn bộ nhớ cache cho npm hoặc pnpm. Đặt ở thư mục tạm của ServBay (/Applications/ServBay/tmp/npm/cache) giúp quản lý tập trung và tránh file cache rải rác trong hệ thống.

Sau khi cấu hình, hãy lưu và đóng file .servbay.config.

Bước 2: Kiểm tra phiên bản trên Terminal của ServBay

1. Mở giao diện chính của ServBay.

2. Bấm nút “Terminal” để mở cửa sổ terminal tích hợp của ServBay.

3. Dùng lệnh cd để di chuyển vào thư mục dự án:

   cd /Applications/ServBay/www/ten-du-an-cua-ban

   (Thay /Applications/ServBay/www/ten-du-an-cua-ban bằng đường dẫn thật của dự án)

4. Chạy lệnh node -v để kiểm tra phiên bản Node.js đang kích hoạt:

   node -v

   Kết quả trả về phải là phiên bản bạn đã chỉ định trong file .servbay.config (ví dụ: v20.x.x).

5. Bạn cũng có thể dùng npm -v (hoặc pnpm -v, yarn -v) để kiểm tra package manager có tương thích đúng với phiên bản Node.js hiện hành không.

Từ bây giờ, mọi lệnh Node.js hoặc npm/pnpm/yarn bạn chạy bên trong thư mục dự án đều sẽ tuân theo phiên bản Node.js cũng như trình quản lý gói đã cấu hình trong .servbay.config.

Ví dụ sử dụng

Sau đây là ví dụ minh họa cách .servbay.config giúp tự động chuyển đổi phiên bản Node.js giữa các dự án khác nhau.

Giả sử bạn có hai dự án: project-a dùng Node.js v18 và project-b dùng Node.js v20.

1. Tạo thư mục và file cấu hình dự án:

   # Tạo 2 thư mục dự án ví dụ trong đường dẫn www của ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Tạo file .servbay.config cho project-a chỉ định Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Tạo file .servbay.config cho project-b chỉ định Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Kiểm tra chuyển đổi phiên bản trên Terminal của ServBay:

   Mở terminal của ServBay và thực hiện các lệnh:

   # Di chuyển vào thư mục project-a
   cd /Applications/ServBay/www/project-a
   # Kiểm tra phiên bản Node.js
   node -v
   # Kết quả kỳ vọng: v18.x.x
   
   # Di chuyển sang thư mục project-b
   cd ../project-b
   # Kiểm tra phiên bản Node.js
   node -v
   # Kết quả kỳ vọng: v20.x.x
   
   # Quay lại project-a
   cd ../project-a
   # Kiểm tra lại Node.js
   node -v
   # Kết quả kỳ vọng: v18.x.x

Qua ví dụ này, bạn có thể thấy ServBay tự động nhận diện thư mục hiện tại và áp dụng thiết lập NODE_VERSION từ file .servbay.config của tương ứng, giúp chuyển đổi giữa nhiều phiên bản Node.js rất mượt mà.

Hình minh họa dưới đây mô tả cách Node.js tự động thay đổi phiên bản dựa trên file .servbay.config khi bạn chuyển đổi giữa các thư mục dự án khác nhau (hình chỉ mang tính minh họa, giao diện thực tế có thể khác):

Lưu ý quan trọng

• File .servbay.config phải đặt trong thư mục dự án hoặc thư mục cha. ServBay sẽ tìm từ thư mục hiện tại lên trên, và chỉ lấy file đầu tiên tìm thấy (file gần nhất).
• Hãy đảm bảo bạn đang sử dụng terminal tích hợp của ServBay, hoặc một terminal ngoài đã được cấu hình đúng biến môi trường từ ServBay.
• Phiên bản bạn chỉ định ở NODE_VERSION phải là phiên bản đã cài đặt và kích hoạt trên ServBay. Nếu không tìm thấy, ServBay sẽ dùng phiên bản mặc định hoặc báo không tồn tại lệnh Node.js.
• Cấu hình trong file .servbay.config chỉ ảnh hưởng đến session terminal hiện tại và các tiến trình con, không ảnh hưởng hệ thống toàn cục hoặc các ứng dụng chạy ngoài môi trường ServBay.

Giải đáp thắc mắc thường gặp (FAQ)

Hỏi: Nếu thư mục dự án của tôi không có file .servbay.config thì sao?

Trả lời: Nếu ServBay không tìm thấy file .servbay.config trong thư mục hiện tại và các thư mục cha, ứng dụng sẽ sử dụng cấu hình toàn cục, hoặc phiên bản Node.js mặc định (thường là phiên bản được đánh dấu “default” trong ServBay).

Hỏi: Làm sao tôi biết ServBay hỗ trợ những phiên bản Node.js nào?

Trả lời: Mở ứng dụng ServBay, chuyển đến mục “Packages” (phía menu bên trái). Tại đây bạn có thể xem danh sách tất cả phiên bản Node.js có sẵn và đã cài đặt. Bạn có thể bật hoặc tắt từng phiên bản theo nhu cầu.

Hỏi: File .servbay.config có gây ảnh hưởng đến toàn bộ hệ thống không?

Trả lời: Không. Các thiết lập trong file .servbay.config chỉ có hiệu lực tạm thời (theo session terminal của ServBay hoặc process dùng biến môi trường ServBay). Không hề ảnh hưởng hay ghi đè biến môi trường ứng dụng khác hoặc hệ thống. Đây chính là cơ chế đảm bảo cách ly môi trường tuyệt đối giữa các dự án.

Hỏi: Ngoài NODE_VERSION, tôi có thể cấu hình gì khác với .servbay.config không?

Trả lời: Có. .servbay.config là cơ chế cấu hình biến môi trường cấp dự án phổ biến của ServBay. Ngoài Node.js, bạn có thể đặt thêm các biến môi trường khác cho dự án thông qua file này. Các thuộc tính hỗ trợ có thể được mở rộng qua từng phiên bản ServBay, nhưng cốt lõi là khai báo các biến môi trường tuân thủ theo quy tắc này.

Tổng kết

Thông qua file .servbay.config của ServBay, bạn có thể dễ dàng và hiệu quả chỉ định cũng như quản lý phiên bản Node.js riêng cho từng dự án phát triển cục bộ. Giải pháp này nhẹ nhàng, thuận tiện hơn nhiều so với các trình quản lý phiên bản truyền thống hoặc giải pháp container, đồng thời tích hợp hoàn hảo với môi trường phát triển của ServBay, giúp xây dựng quy trình phát triển ổn định và thuận lợi cho cộng tác nhóm. Hãy bắt đầu sử dụng .servbay.config trong dự án của bạn ngay hôm nay để tận hưởng sự tiện lợi mà ServBay mang lại!