Giải mã lỗiÍt có điều gì làm dự án bị đình trệ nhanh hơn một dòng chữ đỏ rực trong terminal. Nếu bạn vừa thử chạy npm install và gặp lỗi UNABLE_TO_GET_ISSUER_CERT_LOCALLY, có khả năng bạn đang gặp vấn đề về tin cậy chứng chỉ. Điều này thường xảy ra khi npm cố gắng kết nối với registry nhưng không thể xác minh chứng chỉ bảo mật do mạng của bạn cung cấp.
npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! errno UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! yêu cầu tới https://registry.npmjs.org/package-name thất bại
Nguyên nhân gốc rễTường lửa doanh nghiệp, VPN và các phần mềm diệt virus (như Zscaler hoặc Cisco Umbrella) thường chặn lưu lượng HTTPS để quét các mối đe dọa. Họ thực hiện việc này bằng cách thay thế chứng chỉ gốc của trang web bằng phiên bản tự ký (self-signed) của riêng họ.
Mặc dù Windows có thể tin tưởng chứng chỉ tùy chỉnh này, nhưng Node.js thì không. Node.js sử dụng danh sách các Cơ quan chứng thực (CA) đáng tin cậy được tích hợp sẵn thay vì sử dụng Kho chứng chỉ của Windows (Windows Certificate Store). Khi thấy một chứng chỉ không nhận diện được, nó sẽ ngắt kết nối để bảo vệ bạn.
Giải pháp 1: Sửa lỗi trong 5 giây (Không khuyến nghị cho môi trường Production)Bạn cần một cách xử lý nhanh cho dự án cá nhân? Bạn có thể yêu cầu npm ngừng kiểm tra SSL khắt khe. Đây là cách nhanh nhất để quay lại làm việc, nhưng nó tạo ra một lỗ hổng bảo mật. Nó khiến bạn dễ bị tấn công giả mạo (Man-in-the-Middle - MitM) vì npm sẽ không còn xác minh danh tính của bên mà nó đang giao tiếp.
Chạy lệnh này trong terminal của bạn:
npm config set strict-ssl false
Sau khi cài đặt xong, bạn nên bật lại tính năng này để đảm bảo an toàn:
npm config set strict-ssl true
Giải pháp 2: Cách tiếp cận an toàn (Khuyến nghị)Cách đúng đắn để khắc phục lỗi này là hướng dẫn Node.js tin tưởng chứng chỉ của công ty bạn. Bạn sẽ cần lấy chứng chỉ gốc (thường là tệp .pem hoặc .cer dung lượng nhỏ khoảng 2KB) và chỉ định cho npm sử dụng nó.
Cách xuất chứng chỉ qua Chrome:- Truy cập https://registry.npmjs.org trong trình duyệt.- Nhấp vào biểu tượng Ổ khóa trên thanh địa chỉ > Kết nối an toàn > Chứng chỉ hợp lệ.- Mở tab Chi tiết (Details). Chọn chứng chỉ cao nhất trong cấu trúc phân cấp (Root CA).- Nhấp vào Xuất (Export) và lưu dưới dạng tệp Base64-encoded X.509 (.CER).Sau khi lưu, hãy cho npm biết nơi tìm tệp đó:
npm config set cafile "C:\Users\YourName\Documents\root-cert.pem"
Giải pháp 3: Thiết lập biến môi trường toàn cụcĐôi khi chỉ sửa lỗi cho npm là chưa đủ. Các công cụ khác như tiện ích mở rộng VS Code hoặc các script build dựa trên Node vẫn có thể thất bại. Bạn có thể giải quyết vấn đề này cho tất cả ứng dụng Node.js cùng lúc bằng cách thiết lập biến môi trường hệ thống.
- Nhấn phím Windows và nhập "env". Chọn Edit the system environment variables (Chỉnh sửa biến môi trường hệ thống).- Nhấp vào Environment Variables ở góc dưới bên phải.- Trong mục User variables, nhấp vào New.- Đặt tên là
NODE_EXTRA_CA_CERTS.- Đặt giá trị là đường dẫn đầy đủ đến chứng chỉ của bạn (ví dụ:C:\certs\company-ca.pem).Lưu ý: Bạn phải đóng và mở lại terminal hoặc VS Code để thay đổi này có hiệu lực.
Xác minh: Đã hoạt động chưa?Xác nhận các cài đặt của bạn đã hoạt động bằng cách kiểm tra danh sách cấu hình:
npm config list
Tìm các dòng cafile hoặc strict-ssl. Để kiểm tra thực tế, hãy thử cài đặt một package nhỏ, không có dependency như is-number:
npm install is-number
Nếu thanh tiến trình chạy mà không gặp lỗi ISSUER_CERT, bạn đã thành công.