Khắc phục sự cố Node.js

Tài liệu này nhằm hỗ trợ các lập trình viên sử dụng môi trường phát triển cục bộ ServBay giải quyết một số vấn đề phổ biến gặp phải khi sử dụng các gói phần mềm Node.js.

Không tìm thấy phiên bản lệnh Node.js/npm/pnpm/yarn

Khi bạn làm việc với Node.js, npm, pnpm hoặc yarn trong ServBay, nếu gặp cảnh báo hoặc lỗi như sau, nghĩa là hệ thống không thể tìm thấy tệp thực thi của phiên bản Node.js bạn yêu cầu:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

Nguyên nhân thường là do phiên bản Node.js cụ thể bạn muốn sử dụng chưa được cài đặt qua ServBay, hoặc bạn muốn sử dụng Node.js được cài qua nvm hoặc homebrew nhưng do cấu hình môi trường hệ thống khiến ServBay không thể phát hiện ra các phiên bản đó.

Lưu ý

Sau khi cài đặt ServBay, hệ thống sẽ thiết lập các Script Alias để ưu tiên sử dụng các gói Node.js do ServBay cài đặt sẵn. Khi không tìm thấy phiên bản chỉ định trong ServBay, hệ thống sẽ tự động tìm và sử dụng phiên bản được cài đặt bằng nvm, sau đó mới đến homebrew. Nếu không phát hiện được ở những vị trí này, lỗi như trên sẽ xuất hiện.

Phân tích nguyên nhân:

1. Phiên bản Node.js mà bạn muốn dùng chưa được cài đặt trong ứng dụng ServBay.
2. Máy bạn đã cài đặt nvm hoặc homebrew và bạn muốn sử dụng Node.js do chúng quản lý, nhưng các biến môi trường shell (đặc biệt là PATH hoặc NVM_BIN) thiết lập chưa đúng, khiến ServBay không thể phát hiện các phiên bản Node.js này.

Cách khắc phục:

Nếu bạn đã sử dụng nvm để cài Node.js nhưng vẫn gặp lỗi này, thường nguyên nhân là biến môi trường NVM_BIN trong shell chưa được thiết lập hoặc bị sai. Khi cài đặt nvm đúng chuẩn, biến này sẽ tự động được thiết lập, trỏ đến đường dẫn chứa tệp thực thi Node.js mà nvm quản lý, đây là chìa khóa để nvm hoạt động đúng.

Bạn cần kiểm tra và cập nhật cấu hình shell (~/.zshrc, ~/.bash_profile, v.v…), đảm bảo các dòng khởi tạo nvm và xuất (export NVM_BIN=...) đang thiết lập đúng. Sau đó, tải lại file cấu hình (chạy source ~/.zshrc hoặc khởi động lại terminal). Khi thiết lập xong, cơ chế tìm kiếm của ServBay sẽ hoạt động bình thường với các phiên bản Node.js được quản lý bởi nvm.

Nếu bạn không sử dụng nvm hoặc homebrew, hoặc muốn ưu tiên sử dụng Node.js do ServBay cung cấp, hãy đảm bảo phiên bản Node.js bạn cần đã được cài đặt từ giao diện “Gói phần mềm” (Packages) của ứng dụng ServBay.

Lỗi không hỗ trợ kiến trúc khi sử dụng các gói npm như node-sass

Đối với người dùng macOS sử dụng chip Apple Silicon (M1/M2/M3/M4 - Arm64), khi làm việc với một số gói npm cũ hoặc có mô-đun native như node-sass, bạn có thể gặp lỗi kiểu Unsupported architecture (arm64). Nguyên nhân là vì các bản cũ của những gói này chỉ cung cấp phiên bản biên dịch cho kiến trúc x86_64 mà không hỗ trợ Arm64.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

Phân tích nguyên nhân:

Một số gói npm chứa mã nguồn C++ hoặc các mã native (mã trình điều khiển phần cứng) cần biên dịch cho từng kiến trúc CPU cụ thể. Phiên bản cũ của các gói này thường chưa hỗ trợ Arm64 (Apple Silicon), chỉ tương thích với x86_64.

Cách khắc phục:

1. Nên chuyển sang sử dụng các gói hiện đại hỗ trợ Arm64 (Khuyến nghị nhất):

   Lời khuyên hàng đầu là chuyển sang các giải pháp thay thế hiện đại có hỗ trợ đầy đủ Arm64. Ví dụ, hãy thay thế node-sass (đã lỗi thời, bảo trì kém) bằng gói sass hiện đại mạnh mẽ và được cập nhật thường xuyên. Phần lớn các dự án và toolchain front-end hiện tại đã hỗ trợ tốt sass.

   npm uninstall node-sass
   npm install --save-dev sass

2. Cài Node.js kiến trúc x86_64 trong ServBay và chạy qua Rosetta 2 (Không khuyến nghị):

   ServBay cho phép bạn cài đặt Node.js bản x86_64. Trên máy Mac Apple Silicon, bạn có thể dùng cơ chế dịch Rosetta 2 tích hợp của macOS để chạy Node.js và các mô-đun native xây cho x86_64. Bạn có thể chọn cài đặt Node.js bản x86_64 trong phần “Gói phần mềm” của ứng dụng ServBay.

   

   Lưu ý: Đây không phải là giải pháp lâu dài nên dùng, vì phụ thuộc vào giả lập Rosetta 2, có thể gây giảm hiệu năng và một số rủi ro về tương thích so với môi trường Arm64 nguyên bản. Hãy ưu tiên giải pháp 1 ở trên.

---