Chuyện Gì Đang Xảy Ra
Bạn chạy npm install và bị đập ngay vào mặt lỗi này:
npm ERR! code EINTEGRITY
npm ERR! Verification failed while extracting lodash@4.17.21:
npm ERR! sha512-... integrity checksum failed when using sha512: wanted sha512-ABC... but got sha512-XYZ...
npm tải package về, rồi so sánh checksum của nó với giá trị lưu trong package-lock.json. Hai bên không khớp. npm dừng lại ngay — nó không thể biết file bị hỏng trong quá trình tải, bị giả mạo, hay chỉ là cache cũ trả về. Vậy là nó bail.
Nguyên Nhân Gốc Rễ
- Cache npm bị hỏng — thủ phạm trong hầu hết các trường hợp. Một tarball được cache bị hỏng do lỗi đĩa, tải dở chừng, hoặc phần mềm antivirus scan giữa lúc đang ghi.
package-lock.jsoncũ — lock file chứa hash từ phiên bản package cũ không còn khớp với những gì registry đang phục vụ hiện tại.- Tải xuống không hoàn chỉnh — mạng bị ngắt giữa chừng. npm cache lại file bị hỏng và tiếp tục dùng lại nó mỗi lần install sau đó.
- Registry không khớp — bạn chuyển qua lại giữa registry công khai npmjs.org và mirror Nexus hoặc Artifactory nội bộ. Hash đơn giản là không khớp giữa các registry.
node_modulescòn sót lại — các artifact cài đặt cũ từ lần chạy package manager trước gây xung đột với lần resolve hiện tại.
Cách Sửa Từng Bước
Bước 1 — Xóa cache npm
Bắt đầu từ đây. Cách này giải quyết lỗi trong khoảng 90% trường hợp.
npm cache các tarball đã tải tại ~/.npm trên Linux/macOS, hoặc %APPDATA%\npm-cache trên Windows. Chỉ cần một entry bị hỏng là đầu độc mọi lần install cho đến khi bạn xóa sạch.
npm cache clean --force
Sau đó xác minh cache đã thực sự trống:
npm cache verify
Xóa thành công sẽ trông như thế này:
Cache verified and compressed (~/.npm/_cacache):
Content verified: 0 (0 bytes)
Index entries: 0
Finished in 0.234s
Giờ thử lại npm install. Nếu chạy được, xong.
Bước 2 — Xóa node_modules và lock file
Cache đã sạch nhưng lỗi vẫn còn? Xóa toàn bộ trạng thái cài đặt cục bộ.
# Linux / macOS
rm -rf node_modules package-lock.json
# Windows (PowerShell)
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
Sau đó cài lại từ đầu:
npm install
npm tải mọi thứ trực tiếp từ registry và ghi một package-lock.json mới tinh với hash chính xác. Không còn dữ liệu cũ, không còn không khớp.
Bước 3 — Cài đặt với --prefer-online
Cần giữ lại lock file — chẳng hạn vì team bạn commit nó? Bỏ qua cache mà không cần xóa gì cả:
npm install --prefer-online
Lệnh này bảo npm luôn lấy từ registry thay vì cache cục bộ. Là fallback cho các phiên bản npm cũ hơn:
npm install --cache /tmp/empty-cache
Bước 4 — Kiểm tra registry
Gần đây chuyển qua lại giữa registry công ty và registry công khai? Hash không khớp là chuyện bình thường — mỗi registry ký package theo cách khác nhau.
npm config get registry
Đang trỏ vào chỗ không mong muốn? Đặt lại:
npm config set registry https://registry.npmjs.org/
Nếu setup của bạn yêu cầu dùng registry nội bộ, hãy liên hệ với team infra. Họ cần publish đúng integrity hash trên mirror đó.
Bước 5 — Nhắm vào đúng package bị lỗi
Thông báo lỗi nêu tên package gây ra vấn đề. Nếu chỉ một package, đừng xóa hết — chỉ cần cài lại package đó:
npm install lodash@4.17.21 --prefer-online
Hoặc gỡ rồi cài lại sạch:
npm uninstall lodash
npm install lodash
Bước 6 — Cập nhật npm
Các phiên bản npm dưới 8 có lỗi đã biết trong việc kiểm tra integrity. Kiểm tra phiên bản trước:
npm --version
Dưới 8? Cập nhật:
npm install -g npm@latest
Xác Nhận Đã Sửa Xong
Chạy cài đặt sạch:
npm install
Thấy added 847 packages (hoặc con số của bạn) mà không có lỗi? Ổn rồi. Kiểm tra lại cây dependency xem có sạch không:
npm ls --depth=0
Không có cảnh báo, không có package thiếu — xong.
Xác Minh Hash Thủ Công (Tùy Chọn)
Muốn xem npm đang kiểm tra hash nào? Mở package-lock.json và tìm entry của package:
"lodash": {
"version": "4.17.21",
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
"integrity": "sha512-v2kDE..."
}
Trường integrity đó là hash SHA-512 được mã hóa base64. Để xác minh tarball thủ công, Hash Generator trên ToolCraft tính MD5, SHA-256 và SHA-512 ngay trên trình duyệt — không có gì rời khỏi máy bạn. Rất tiện khi debug một mirror artifact nội bộ và cần so sánh hash mà không cần mở CLI.
Phòng Ngừa
- Luôn commit
package-lock.json— mọi developer và mọi lần chạy CI đều cài đúng phiên bản với hash đã được xác minh. - Dùng
npm citrong CI thay vìnpm install. Nó nghiêm ngặt hơn: báo lỗi nếu lock file bị thiếu hoặc không đồng bộ, và luôn cài từ đầu. Không bất ngờ. - Đừng trộn lẫn package manager — chạy
yarnrồi lạinpmtrong cùng một project sẽ làm hỏng lock file rất nhanh. - Thêm
npm cache verifynhư một bước preflight trong CI — nếu pipeline của bạn cache npm giữa các lần build, một bước verify nhanh sẽ phát hiện hỏng hóc trước khi nó phá vỡ quá trình cài đặt.
Tham Khảo Nhanh
# Cách 1: Xóa cache (thử cái này trước — hiệu quả 90% trường hợp)
npm cache clean --force && npm install
# Cách 2: Cài lại hoàn toàn từ đầu
rm -rf node_modules package-lock.json && npm install
# Cách 3: Bỏ qua cache, lấy trực tiếp từ registry
npm install --prefer-online
# Cách 4: Đặt lại về registry công khai
npm config set registry https://registry.npmjs.org/ && npm install
# Cách 5: Cập nhật npm
npm install -g npm@latest