Про фикс NODE_OPTIONS=--openssl-legacy-provider

У меня на работе в каждом втором проекте, который использует Node.js 17+, добавлен этот параметр при запуске npm run build или pnpm run dev. Хочется понять, что же он значит, а значит, пришло время покопаться.

Начнём с того, что если убрать NODE_OPTIONS=--openssl-legacy-provider, то приложение может упасть с такой ошибкой:

error:0308010C:digital envelope routines::unsupported
at new Hash (node:internal/crypto/hash:69:19)
at Object.createHash (node:crypto:133:10)

Проблема появилась, когда Node.js 17 решили переехать на новую версию библиотеки OpenSSL. Её версия 3.0 использует новые методы шифрования, а многие старые методы (например, md4) оказались неподдерживаемыми.

В свою очередь, на методах из OpenSSL основана и Node.js библиотека crypto (мы можем увидеть её упоминание в самом коде ошибки).

А тут уже Webpack, и некоторые другие библиотеки, особенно устаревших версий, могут использовать старые алгоритмы шифрования из crypto. Далеко ходить не надо, вот ишью в Webpack 5 про использование md4.

Получается такая цепочка:
→ мы на нашем проекте используем, например, webpack
→ он использует алгоритм шифрования md4 из встроенной Node.js-библиотеки crypto
→ сам Node.js уже использует OpenSSL версии 3.0, а поэтому и md4 в crypto больше не работает
→ ловим ошибку при попытке собрать приложение

Если бы команда Node.js в свое время выкатила релиз без возможности поддержки старых инструментов, то у нас бы сломалось пол интернета. Поэтому они, конечно, предусмотрели фикс - та самая опция --openssl-legacy-provider, которая позволяет использовать Legacy версию OpenSSL. Мы можем или добавить опцию сразу в консольную команду:

node --openssl-legacy-provider server.js

или через специальный параметр, как встречается чаще всего:

NODE_OPTIONS=--openssl-legacy-provider npm run build

Но конечно, лучше всего отказываться или обновлять библиотеки, которые требуют устаревший алгоритм (+1 причина переходить с Webpack на Vite)))