Cách khắc phục lỗi Node.js 'digital envelope routines::unsupported' (OpenSSL 3.0)

Chuyện gì đã xảy ra?Có lẽ bạn vừa nâng cấp môi trường máy cục bộ lên Node.js v18 hoặc v20 với hy vọng tăng hiệu suất. Nhưng thay vào đó, dự án React cũ của bạn đã bị lỗi ngay khi chạy npm start. Lỗi cụ thể này thường xuất hiện khi các công cụ build cũ gặp phải các tiêu chuẩn bảo mật nghiêm ngặt hơn của các phiên bản Node.js hiện đại.

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:71:19)
    at Object.createHash (node:crypto:133:10)
    at /node_modules/webpack/lib/util/createHash.js:135:53

Tại sao quá trình Build bị lỗiRắc rối bắt đầu từ Node.js v17. Phiên bản đó đã thay thế OpenSSL 1.1.1 bằng OpenSSL 3.0. Lớp bảo mật mới này khắt khe hơn nhiều. Nó chuyển các thuật toán cũ, không còn an toàn như MD4 vào một "legacy provider" (nhà cung cấp cũ) vốn bị vô hiệu hóa theo mặc định.

Webpack 4 và các phiên bản cũ của Create React App (v4 trở xuống) sử dụng MD4 để tạo hash cho tệp. Khi các công cụ này cố gắng gọi hàm băm, OpenSSL 3.0 sẽ chặn yêu cầu vì nó không còn coi quy trình đó là "an toàn" nữa. Kết quả là? Quá trình build của bạn dừng lại ngay lập tức.

Cách sửa nhanh: Biến môi trườngNếu bạn đang gấp, bạn có thể ép Node.js sử dụng legacy provider. Cách này giúp bỏ qua bước kiểm tra bảo mật nghiêm ngặt mà không cần thay đổi mã nguồn. Đây là một giải pháp tạm thời đáng tin cậy cho việc phát triển ở máy cục bộ.

Trên Linux hoặc macOSChạy lệnh này trong terminal trước khi khởi động dự án của bạn:

export NODE_OPTIONS=--openssl-legacy-provider
npm start

Trên Windows (Command Prompt)```

set NODE_OPTIONS=--openssl-legacy-provider npm start

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

Cách tốt hơn: Cập nhật package.jsonViệc nhập lệnh export thủ công rất tốn công. Tốt hơn là nên tự động hóa việc này trong package.json để các thành viên khác trong nhóm không gặp phải lỗi tương tự. Tuy nhiên, vì các hệ điều hành khác nhau xử lý biến môi trường khác nhau, gói cross-env là lựa chọn an toàn nhất.

Đầu tiên, cài đặt gói hỗ trợ:

npm install cross-env --save-dev

Tiếp theo, cập nhật phần scripts. Điều này đảm bảo bản sửa lỗi hoạt động mượt mà trên Windows, Mac và Linux:

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

Giải pháp lâu dài: Nâng cấp Stack của bạnViệc sửa lỗi bằng biến môi trường về mặt kỹ thuật chỉ là một giải pháp thay thế. Bạn vẫn đang sử dụng các thuật toán đã lỗi thời. Nếu có thời gian, giải pháp "chuẩn" là chuyển sang các công cụ hỗ trợ OpenSSL 3.0 một cách nguyên bản.

• Nâng cấp Webpack: Chuyển sang Webpack 5.20.0 hoặc cao hơn. Phiên bản này cho phép bạn thay đổi thuật toán băm thành xxhash64, nhanh hơn và tương thích tốt hơn.
• Nâng cấp CRA: Nếu bạn dùng Create React App, hãy chuyển sang react-scripts v5.0.0+.
• Sử dụng NVM: Nếu bạn không thể nâng cấp dự án, hãy sử dụng Node Version Manager để chuyển về Node.js v16.14.0 (LTS). Phiên bản này sử dụng OpenSSL 1.1.1 cũ hơn và sẽ không gây ra lỗi này.

nvm install 16
nvm use 16

Sửa lỗi trên Docker & CI/CDNếu pipeline Jenkins hoặc GitHub Actions của bạn bị lỗi, hãy thêm flag vào Dockerfile của bạn. Điều này ngăn quá trình build bị crash trong môi trường container:

# Sử dụng flag trong quá trình build
ENV NODE_OPTIONS=--openssl-legacy-provider
RUN npm run build

Cách xác minh bản sửa lỗiĐừng chỉ mặc định là nó đã hoạt động. Hãy làm theo các bước sau để xác nhận:

• Xóa thư mục node_modules/.cache để dọn dẹp các bản build cũ.
• Thực thi npm run build.
• Kiểm tra thư mục /build hoặc /dist. Nếu các tệp được tạo ra và terminal báo "Compiled successfully," thì mọi thứ đã ổn.
• Chạy node --help | grep openssl-legacy-provider. Nếu nó trả về kết quả, phiên bản Node hiện tại của bạn đã nhận diện flag này.