Come installare Node.js e NPM su Debian 11 Bullseye

Su Debian 11 Bullseye la scelta più solida per avere Node.js e NPM aggiornati, senza inseguire pacchetti vecchi nei repository base, è partire da una fonte affidabile e verificabile. Il punto non è solo “farlo installare”: è evitare di ritrovarsi con una versione troppo datata per il progetto, oppure con un ambiente sporco che poi complica aggiornamenti e troubleshooting.

© TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster — https://trgtkls.it — tutti i diritti riservati.

La strada più lineare è usare il repository ufficiale di NodeSource, che su Debian 11 copre bene i casi comuni di sviluppo e deploy. Se invece devi gestire più versioni sullo stesso server o sul portatile di sviluppo, NVM resta spesso la soluzione più flessibile. In questo articolo trovi entrambe le opzioni, con verifiche pratiche e un criterio semplice per scegliere senza andare a tentativi.

Quale metodo scegliere su Debian 11 Bullseye

Prima di toccare il sistema conviene chiarire l’obiettivo. Se stai preparando una macchina per eseguire una sola applicazione o un singolo stack, il repository ufficiale di NodeSource è in genere la scelta più pulita. Se invece lavori su più progetti con requisiti diversi, oppure devi testare versioni differenti di Node.js, NVM è più adatto perché installa le versioni a livello utente e non forza un solo binario globale.

Su Debian 11 i pacchetti nel repository standard possono essere sufficienti solo per scenari molto conservativi. Il problema è che spesso la versione disponibile non coincide con quella richiesta dal progetto, dal framework o dal toolchain frontend. Per questo, in un contesto reale, ha più senso partire da una versione esplicitamente gestita e poi allineare il resto dell’ambiente.

Installazione con repository NodeSource

Questo è il metodo consigliato quando vuoi un’installazione globale, leggibile e relativamente semplice da mantenere. Il vantaggio è che node e npm arrivano come pacchetti Debian gestiti da APT, quindi aggiornamenti e rimozioni restano ordinati.

Prima di tutto aggiorna l’indice dei pacchetti e installa i prerequisiti minimi:

sudo apt update
sudo apt install -y ca-certificates curl gnupg

Il pacchetto ca-certificates serve per la validazione TLS, curl per recuperare lo script di bootstrap e gnupg per la gestione della chiave del repository. Se uno di questi manca, il setup può fallire o costringerti a workaround inutili.

Il passaggio successivo è aggiungere il repository NodeSource. Sostituisci 20.x con la major che ti serve davvero; se il progetto richiede un’altra release, cambia il numero in modo esplicito e documentalo nel change log:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

Questo comando aggiunge il repository e importa i riferimenti necessari per APT. Il rischio operativo è basso, ma va sempre considerato il fatto che stai introducendo una nuova sorgente di pacchetti nel sistema. Se lavori in produzione o su una macchina critica, annota la modifica e verifica che il repository sia effettivamente quello atteso prima di installare i pacchetti.

A questo punto installa Node.js:

sudo apt install -y nodejs

In molte situazioni npm viene installato insieme a nodejs. Su alcune versioni o combinazioni di pacchetti potresti trovare anche strumenti aggiuntivi come build-essential utili per compilare dipendenze native, ma non sono obbligatori nel primo step. Conviene aggiungerli solo se il tuo progetto li richiede davvero.

Verifica immediata dell’installazione

Dopo l’installazione, controlla subito binari e versioni. È un test banale ma evita di scoprire problemi quando il deploy è già in corso:

node -v
npm -v
which node
which npm

L’output atteso è una versione valida per entrambi i comandi, più un percorso coerente con il sistema, in genere sotto /usr/bin/. Se node -v funziona ma npm -v no, di solito il problema è un’installazione incompleta o un conflitto con vecchi pacchetti presenti in precedenza.

Un controllo utile in più è verificare che il pacchetto provenga dalla sorgente corretta:

apt-cache policy nodejs

Qui dovresti vedere il repository NodeSource tra le candidate versioni. Se compare solo il repository Debian standard, significa che il setup del repository non è andato a buon fine oppure che non è stato aggiornato correttamente l’indice APT.

Installare una versione specifica di Node.js

NodeSource non serve solo per installare “l’ultima versione disponibile”, ma anche per fissare una major precisa. Questo è importante quando un’applicazione è stata validata su una release specifica di Node.js e un upgrade non è ancora stato testato.

La regola pratica è semplice: scegli una major supportata dal progetto e mantienila coerente tra sviluppo, staging e produzione. Se il codice usa dipendenze native o strumenti che cambiano comportamento tra major diverse, un allineamento approssimativo può generare bug difficili da leggere nei log.

Per cambiare versione, rimuovi il repository precedente solo se necessario e ripeti il bootstrap con la major desiderata. Per esempio, per una 18.x:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Se devi fare un downgrade o un cambio di major su un sistema già usato da applicazioni esistenti, il blast radius non è banale: i moduli installati globalmente possono non essere compatibili, e gli script di build potrebbero richiedere una versione diversa di npm. Prima di cambiare, verifica almeno quali servizi o pipeline dipendono da quel binario.

Installazione con NVM per ambienti multi-versione

NVM, cioè Node Version Manager, è il metodo giusto quando vuoi evitare che una singola installazione globale condizioni tutto il sistema. È molto utile su workstation di sviluppo, macchine di test e ambienti in cui ogni progetto ha la propria versione di Node.js.

Il vantaggio principale è la separazione: ogni utente può avere la propria versione, e puoi passare da una release all’altra senza toccare i pacchetti di sistema. Il rovescio della medaglia è che l’installazione dipende dalla shell dell’utente e dal profilo caricato correttamente, quindi va verificata con più attenzione rispetto a un pacchetto APT.

Per installare NVM, usa lo script ufficiale del progetto. In questo caso conviene scaricare lo script e leggerlo prima di eseguirlo, soprattutto se lo stai usando in un contesto non personale:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Dopo l’installazione, ricarica la shell oppure apri una nuova sessione. Il file di configurazione viene in genere aggiunto a ~/.bashrc, ~/.zshrc o al profilo equivalente, a seconda della shell usata. Se l’installazione sembra andata a buon fine ma il comando nvm non esiste, il problema è quasi sempre il mancato sourcing del profilo utente.

Verifica che NVM sia disponibile:

command -v nvm

Se il comando restituisce nvm, puoi installare la versione desiderata di Node.js. Per esempio, una release LTS tipica:

nvm install --lts
nvm use --lts
node -v
npm -v

Con NVM puoi anche installare versioni multiple e scegliere quella attiva al volo:

nvm install 18
nvm install 20
nvm use 18
node -v

Questa flessibilità è ottima in sviluppo, ma richiede disciplina. Se un servizio di produzione dipende da Node.js avviato tramite systemd o da un utente non interattivo, bisogna essere certi che l’ambiente carichi la versione corretta. In quei casi, una installazione globale via APT o un meccanismo di deploy esplicito può essere più prevedibile.

Allineare npm, npx e la toolchain di progetto

Installare Node.js non chiude il lavoro: in pratica devi verificare che anche npm e, se serve, npx si comportino come previsto. Molti progetti moderni usano script di build, generatori e CLI che si appoggiano proprio a questi strumenti.

Controlla i dettagli della versione installata:

npm -v
npx -v
npm config get prefix

Il valore di prefix è utile perché ti dice dove vengono installati i pacchetti globali. Se stai usando NVM, quel percorso sarà nel profilo utente; se stai usando il pacchetto di sistema, sarà coerente con l’installazione globale. Questo dettaglio diventa importante quando un comando globale non viene trovato o quando una pipeline CI vede un comportamento diverso dalla shell interattiva.

Se devi installare pacchetti globali, fallo in modo consapevole. Per esempio:

npm install -g pm2

Qui il rischio non è il comando in sé, ma la dispersione: installare troppi tool globali senza tracciarli rende difficile capire da dove arrivano gli script usati dai progetti. Quando possibile, preferisci le dipendenze locali al progetto e usa i comandi esposti da package.json.

Problemi comuni su Debian 11 e come leggere i sintomi

Se l’installazione fallisce, il sintomo più utile da guardare è il messaggio APT o il risultato di node -v. Un errore TLS durante il bootstrap del repository di solito indica certificati mancanti, orologio di sistema errato o problemi di rete. Un errore di firma o repository non trovato indica invece un problema di configurazione del source list o della chiave associata.

Quando node è installato ma npm non lo è, conviene verificare se ci sono pacchetti residui o conflitti con installazioni precedenti. Su macchine “vecchie” o toccate da più amministratori, capita spesso di avere binari sovrapposti in /usr/local/bin e /usr/bin. In quel caso il comando which node o type -a node aiuta più di qualunque supposizione.

Se invece il problema emerge quando avvii un’applicazione, non limitarti a controllare la versione. Guarda anche variabili d’ambiente, permessi sulla directory del progetto, ownership dei file e presenza di moduli compilati per la versione sbagliata. Molti errori apparentemente “di Node.js” sono in realtà errori di filesystem o di runtime avviato con un utente diverso da quello usato in test.

Rimozione o cambio metodo senza sporcare il sistema

Se hai installato Node.js con NodeSource e vuoi passare a NVM, oppure vuoi semplicemente ripulire una macchina, fai prima una verifica di cosa è effettivamente presente. La rimozione cieca può lasciare residui o, peggio, togliere un binario che altri servizi usano ancora.

Per controllare i pacchetti installati:

dpkg -l | grep -E '^ii\s+nodejs|^ii\s+npm'

Se vuoi rimuovere l’installazione globale gestita da APT, il comando tipico è questo:

sudo apt remove -y nodejs
sudo apt autoremove -y

Il blast radius qui è moderato ma reale: elimini il runtime per tutti gli utenti che dipendono da quell’installazione. Prima di procedere, verifica se esistono servizi attivi, script cron o pipeline che invocano node. Il rollback, in questo caso, è reinstallare la stessa major con lo stesso repository usato in precedenza.

Con NVM, invece, la rimozione è più circoscritta all’utente. Puoi eliminare una versione specifica senza toccare il sistema intero:

nvm uninstall 18

Anche qui il rollback è semplice: reinstalli la versione necessaria con nvm install. Il vero punto da controllare è che nessun progetto puntasse a quella versione in modo implicito.

Scelta pratica finale tra Debian package, NodeSource e NVM

Se devi mettere in piedi un server applicativo con un solo runtime Node.js, NodeSource è in genere il compromesso migliore tra semplicità e manutenzione. Se devi lavorare su più progetti, testare release diverse o mantenere un ambiente di sviluppo flessibile, NVM è più adatto. Il repository Debian standard resta utile solo quando la versione disponibile è sufficiente per il tuo caso d’uso e non hai bisogno di aggiornamenti rapidi.

In sintesi operativa: scegli il metodo in base al ciclo di vita del progetto, non per abitudine. La versione di Node.js è una dipendenza a tutti gli effetti, e trattarla come tale evita problemi più avanti su build, moduli nativi, compatibilità di npm e ripetibilità degli ambienti.

Assunzioni: Debian 11 Bullseye aggiornato, accesso sudo disponibile, nessuna policy aziendale che imponga un mirror interno o una versione Node.js specifica.