Fix lỗi 'Error: error:0308010C:digital envelope routines::unsupported' (ERR_OSSL_EVP_UNSUPPORTED) trong Node.js

Chuyện gì đang xảy raBạn chạy build hoặc khởi động dev server và gặp phải lỗi này:

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    at Object.createHash (node:crypto:130:10)
    ...
ERR_OSSL_EVP_UNSUPPORTED

Node.js 17+ đi kèm với OpenSSL 3. Vấn đề là gì? Project của bạn vẫn đang phụ thuộc vào các công cụ cũ hơn — webpack 4, react-scripts v4, hoặc bất kỳ package nào gọi các API mã hóa mà OpenSSL 3 đã loại bỏ. Code của bạn không thay đổi. Runtime mới thay đổi. Cụ thể, OpenSSL 3 đã loại bỏ hỗ trợ băm dựa trên MD4 — chính xác là thứ webpack 4 sử dụng nội bộ để tạo hash cho các chunk. Đó là toàn bộ xung đột nói gọn trong một câu.

Xác nhận môi trườngChạy hai lệnh này trước:

node -v
openssl version

Node.js 17+ kết hợp với OpenSSL 3.x chính là thủ phạm. Stack trace cũng là một dấu hiệu rõ ràng — hầu như luôn trỏ đến node:internal/crypto/hash hoặc một module webpack bị chôn vùi vài frame bên dưới.

Các giải pháp### Tùy chọn 1: Đặt NODE_OPTIONS (sửa nhanh, phù hợp cho CI/local dev)Chỉ cần một biến môi trường là đủ để bạn thoát khỏi tình trạng bế tắc ngay lúc này:

# Linux / macOS
export NODE_OPTIONS=--openssl-legacy-provider
npm start

# Windows (Command Prompt)
set NODE_OPTIONS=--openssl-legacy-provider
npm start

# Windows (PowerShell)
$env:NODE_OPTIONS="--openssl-legacy-provider"
npm start

Chán phải đặt lại mỗi phiên làm việc? Hãy nhúng nó vào package.json để cả team tự động có ngay:

{
  "scripts": {
    "start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
    "build": "NODE_OPTIONS=--openssl-legacy-provider react-scripts build"
  }
}

Lưu ý: cách này kích hoạt lại hành vi đã bị deprecated. Nó hoạt động, nhưng chỉ là giải pháp tạm thời — không phải đích đến lâu dài. Hãy lên kế hoạch để vượt qua nó sớm.

Tùy chọn 2: Nâng cấp react-scripts (dành cho các project Create React App)Vẫn đang dùng react-scripts v4? Phiên bản 5 đã chuyển sang webpack 5 và xử lý OpenSSL 3 mà không cần bất kỳ workaround nào:

npm install react-scripts@latest

Hãy bỏ cờ NODE_OPTIONS sau khi nâng cấp và chạy build đầy đủ để xác nhận. react-scripts 5 hoạt động với Node.js 18+ ngay từ đầu — không cần flag nào thêm.

Tùy chọn 3: Nâng cấp webpack (dành cho các setup webpack tùy chỉnh)Tự quản lý webpack? Hãy chuyển từ v4 lên v5:

npm install webpack@latest webpack-cli@latest

webpack 5 tạo hash cho chunk bằng thuật toán khác hoàn toàn tương thích với OpenSSL 3. Tuy nhiên có các thay đổi breaking trong quá trình nâng cấp — hãy lướt qua hướng dẫn migration chính thức trước khi bắt tay vào làm.

Tùy chọn 4: Hạ cấp Node.js (biện pháp cuối cùng)Chưa thể động vào dependencies ngay lúc này? Hãy ghim về Node.js 16, phiên bản đi kèm với OpenSSL 1.1.1:

# Dùng nvm
nvm install 16
nvm use 16

# Đặt làm mặc định
nvm alias default 16

Commit file .nvmrc để mọi người trong team dùng cùng một phiên bản:

echo "16" > .nvmrc

Một điểm cần lưu ý: Node.js 16 đã kết thúc vòng đời vào tháng 9 năm 2023. Cách này giúp bạn có thêm thời gian — không phải là mái nhà lâu dài.

Xác nhận bản sửa lỗiChạy build hoặc dev server của bạn:

npm start
# hoặc
npm run build

Không còn thấy ERR_OSSL_EVP_UNSUPPORTED trong output? Vậy là xong. Nếu bạn đang dùng CI, hãy kiểm tra lại rằng biến môi trường đó thực sự đã được đặt ở đó — đây là nơi bản sửa lỗi thường bị bỏ sót nhất. Muốn kiểm tra trực tiếp crypto của Node? Thử lệnh một dòng này:

node -e "require('crypto').createHash('md4').update('test').digest('hex')"

Trên Node.js 17+ mà không có legacy flag, lệnh đó sẽ báo lỗi. Với --openssl-legacy-provider, nó chạy bình thường. Trên stack đã nâng cấp hoàn toàn (webpack 5 + Node 18+), bạn sẽ không cần md4 nữa — vấn đề tự biến mất.

Chọn giải pháp nào- Sửa nhanh / CI: Đặt NODE_OPTIONS=--openssl-legacy-provider- Dự án CRA: Nâng cấp lên react-scripts@5- Webpack tùy chỉnh: Nâng cấp lên webpack 5- Chưa thể động vào dependencies: Tạm thời ghim Node.js về v16## Cách tránh lỗi này trong tương laiLỗi này thường bất ngờ ập đến khi ai đó nâng cấp Node.js ở cấp global — hoặc CI âm thầm cập nhật runner image — mà không kiểm tra xem build tooling có theo kịp không. Ba thói quen giúp ngăn ngừa điều này:

• Ghim phiên bản Node.js trong .nvmrc và trong trường engines của package.json. Nếu phiên bản không được khai báo rõ ràng, đó là một bất ngờ đang chờ xảy ra.- Trước khi nâng phiên bản major của Node.js, hãy xác minh rằng build tools của bạn có bản release tương thích. Năm phút kiểm tra còn hơn một pipeline bị vỡ.- Nếu bạn vẫn còn dùng --openssl-legacy-provider sau năm 2024, hãy đưa việc nâng cấp build tooling vào backlog. Flag này chưa biến mất ngay, nhưng nó báo hiệu công việc còn dang dở.