Tình huống
Bạn nâng cấp Node.js từ v18 lên v20. Chạy ứng dụng. Và gặp lỗi này:
Error: Cannot find module '../build/Release/addon.node'
Require stack:
- /app/node_modules/bcrypt/lib/bcrypt.js
node_modules vẫn còn đó. Bạn không đụng vào một file config nào. Không có gì thay đổi ngoài phiên bản Node.js. Vậy mà ứng dụng cứ từ chối khởi động.
Tại sao lại xảy ra
Các package như bcrypt, sharp, canvas, sqlite3, và node-sass không phải là JavaScript thuần túy. Chúng chứa code C/C++ được biên dịch thành file nhị phân .node — và file nhị phân đó gắn liền với một phiên bản ABI (Application Binary Interface) cụ thể của Node.js.
Node.js v18 dùng ABI 108. Node.js v20 dùng ABI 115. File nhị phân cũ nói một phương ngữ khác. Node không thể tải nó, vì vậy bạn thấy lỗi "missing module" dù file đó thực sự tồn tại trên ổ đĩa.
Đó cũng là lý do tại sao npm install đơn thuần không giải quyết được. npm thấy package đã được cài và bỏ qua việc biên dịch lại hoàn toàn.
Cách sửa nhanh — build lại native addon
Ba lựa chọn, theo thứ tự khả năng thành công:
Cách 1: npm rebuild (thử trước)
# Chạy từ thư mục gốc của project
npm rebuild
Lệnh này biên dịch lại mọi native addon theo phiên bản Node.js hiện tại. Mất khoảng 30–60 giây với một project thông thường. Thường thì chỉ cần vậy là xong.
Cách 2: Xóa node_modules và cài lại từ đầu
Nếu npm rebuild báo lỗi hoặc để mọi thứ dở dang, hãy cài lại sạch hoàn toàn:
# npm
rm -rf node_modules
npm install
# yarn
rm -rf node_modules
yarn install
# pnpm
rm -rf node_modules
pnpm install
Chậm hơn, nhưng triệt để hơn. Cách này buộc biên dịch lại mọi thứ từ đầu.
Cách 3: Build lại một package cụ thể
Chỉ một addon bị lỗi? Đừng xóa hết. Chỉ định trực tiếp package đó:
npm rebuild bcrypt
Nếu rebuild vẫn thất bại — bạn đang thiếu build tools
Bước biên dịch chạy qua node-gyp, vốn cần trình biên dịch C++ và Python 3 trên máy. Thiếu chúng, bạn sẽ gặp lỗi như gyp ERR! stack Error: not found: make hoặc python: command not found.
Ubuntu/Debian
sudo apt-get install -y build-essential python3
RHEL/CentOS/Amazon Linux
sudo yum groupinstall 'Development Tools'
sudo yum install python3
macOS
xcode-select --install
Lệnh này cài bộ công cụ dòng lệnh dành cho developer của Apple, bao gồm clang và make. Dung lượng tải về khoảng 200 MB.
Windows
Package npm windows-build-tools cũ đã bị deprecated và không hoạt động trên Node.js hiện đại. Hãy vào thẳng nguồn gốc:
- Tải Visual Studio Build Tools 2022 từ trang web của Microsoft
- Trong quá trình cài đặt, chọn workload "Desktop development with C++"
- Đảm bảo Python 3 cũng được cài (trình cài đặt có thể tùy chọn bao gồm nó)
Sau đó, thử lại npm rebuild trong một cửa sổ terminal mới.
Môi trường Docker và CI
Docker là một cạm bẫy phổ biến ở đây. Bạn cập nhật base image từ node:18-alpine lên node:20-alpine, nhưng Docker tái sử dụng một layer được cache vẫn còn chứa các file nhị phân đã biên dịch cũ. Ứng dụng lỗi lúc chạy, trong khi quá trình build image trông có vẻ ổn.
Cách sửa là cài đặt sạch trong Dockerfile, với build tools sẵn có:
FROM node:20-alpine
RUN apk add --no-cache python3 make g++
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
Đang dùng Docker Compose với named volume cho node_modules? Các file nhị phân cũ vẫn nằm trong volume đó dù đã build lại image. Hãy xóa nó đi:
docker-compose down -v
docker-compose up --build
Kiểm tra xem đã sửa xong chưa
Xác nhận rằng file nhị phân .node thực sự đã được biên dịch lại — thời gian tạo file phải là gần đây:
# bcrypt
ls -la node_modules/bcrypt/lib/binding/
# sharp
ls -la node_modules/sharp/build/Release/
Sau đó chạy thử nhanh trước khi khởi động toàn bộ ứng dụng:
node -e "require('bcrypt'); console.log('bcrypt OK')"
node -e "require('sharp'); console.log('sharp OK')"
Nếu chúng in ra OK, bạn đã xong.
Ngăn chặn sự cố này tái diễn
Vấn đề căn bản là sự không khớp phiên bản. Khóa nó lại bằng file .nvmrc trong thư mục gốc của project:
# .nvmrc
20.11.0
Giờ mọi người trong nhóm — và mọi lần chạy CI — đều dùng cùng một phiên bản:
nvm use # tự đọc .nvmrc
GitHub Actions:
- uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
Một file duy nhất, không còn tình trạng lệch phiên bản "chạy được trên máy tôi" nữa.
Mẹo hay
Khi truy tìm sự cố native addon, đôi khi hữu ích khi xác nhận xem file nhị phân .node có thực sự thay đổi sau khi rebuild không. Hash Generator trên ToolCraft cho phép bạn tạo checksum SHA-256 ngay trên trình duyệt — so sánh hash trước và sau khi rebuild để xác nhận file đã được thay thế thực sự, không chỉ được cập nhật timestamp.
Tóm tắt nhanh
- Nguyên nhân gốc rễ: Native addon được biên dịch cho ABI Node.js cũ — không tương thích sau khi nâng cấp (ví dụ: ABI 108 → 115 giữa v18 và v20)
- Cách sửa 1:
npm rebuild - Cách sửa 2: Xóa
node_modules+ cài lại - Cách sửa 3: Cài build tools trước (
build-essentialtrên Linux, Xcode CLI trên macOS, Visual Studio Build Tools trên Windows), rồi rebuild - Docker: Xóa volume cache, build lại image dùng
npm civới build tools trong image - Phòng ngừa: Ghim phiên bản Node.js bằng
.nvmrc