error:0308010C digital envelope routines::unsupported: causa e correzione

Risposta breve: il bundler ha chiesto a OpenSSL 3 un algoritmo, md4, che OpenSSL 3 non espone più nel provider predefinito. Non è un errore del tuo codice e non si corregge nel codice: si corregge aggiornando lo strumento che calcola gli hash, oppure dicendo a Node di riattivare il provider legacy.

Il messaggio esatto

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:79:19)
  opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'

Il prefisso 0308010C è il codice OpenSSL: dice che l'algoritmo richiesto non è disponibile con le impostazioni correnti del provider. Il resto dello stack indica dove Node ha provato a creare l'hash.

Perché succede

Node 17 è passato a OpenSSL 3. Webpack 4, e gli strumenti che lo incapsulano, come create-react-app 4, vue-cli 4 e alcune configurazioni di Next 11, usa md4 per calcolare gli identificatori dei chunk. OpenSSL 3 mette md4 nel provider legacy, disattivato per impostazione predefinita perché considerato debole.

Da qui il paradosso: il progetto non è vecchio di dieci anni, ma un singolo passaggio della build dipende da un algoritmo che il sistema operativo non considera più sicuro.

Correzione rapida, da usare come tampone

# macOS / Linux
NODE_OPTIONS=--openssl-legacy-provider npm run build

# PowerShell
$env:NODE_OPTIONS = "--openssl-legacy-provider"
npm run build

Il flag riattiva il provider legacy per l'intero processo Node. Funziona subito e va bene per sbloccare una build locale. Non va lasciato nella pipeline di produzione: riattiva algoritmi deboli anche per il codice che non ne ha bisogno.

Correzione definitiva

1. Aggiorna il bundler a webpack 5, oppure passa a Vite o rspack.
2. Se usi create-react-app, porta react-scripts alla 5 o migra a Vite: la 4 non riceverà altre correzioni.
3. Se il bundler è bloccato da una dipendenza, isola quella dipendenza: il problema è suo, non di tutto il progetto.

npm ls webpack
npx webpack --version

Il primo comando mostra chi porta webpack nell'albero delle dipendenze; il secondo la versione effettivamente usata. Se la versione è 4, il flag legacy è un sintomo, non la cura.

Quando la correzione non funziona

Se l'errore resta con NODE_OPTIONS impostato, il processo che fallisce non eredita l'ambiente. Succede con script che lanciano un secondo Node, in container senza variabili passate, o in un comando che usa un worker separato. Verifica con node -p process.env.NODE_OPTIONS dentro lo stesso script che fallisce: se stampa vuoto, la variabile non è arrivata.

Come prevenirlo

• Fissa la major di Node in .nvmrc e in engines del package.json.
• Esegui la build in CI con la stessa major usata in locale: la differenza tra le due è la causa più frequente.
• Tratta ogni uso di --openssl-legacy-provider come debito tecnico con una data di scadenza.

Dove continuare

Il catalogo EneUI contiene 111.985 componenti e 1.556 blocchi con preview: sono record già compilati, quindi non ti costringono a ritoccare un toolchain legacy. Per capire quale libreria costa meno in build leggi quanto pesa una libreria UI; per la struttura del progetto App Router nel 2026; per il confronto tra approcci alternative a MUI. La classifica dei cataloghi misurati è in /best/ui-catalogues.