npm ci non aggiorna il lockfile. npm install, quando i range di package.json non tornano, sì. Le due pagine della documentazione npm, etichetta «Version 11.21.0 (Legacy)», rilette il 20 ottobre 2026, non descrivono lo stesso comando. Non ho lanciato i comandi: riporto quello che scrivono npm-ci e npm-install.
In breve: npm ci pretende un package-lock.json o uno npm-shrinkwrap.json, cancella node_modules se c’è, e si ferma se il lock non coincide con package.json. Non scrive né il json né i lock. npm install senza argomenti, se i range non coincidono, risolve versioni nuove e aggiorna il lock. yarn.lock sta nella pagina di install, non tra i file che npm ci dichiara di esigere.
Le cinque differenze scritte sulla pagina ci
La pagina di npm ci dice che il comando somiglia a npm install ed è pensato per ambienti automatici: test, continuous integration, deploy, o qualunque caso in cui si voglia un’installazione pulita. Poi elenca le differenze. Non sono un mio riassunto.
| Sulla pagina npm ci | Conseguenza |
|---|---|
Deve esistere package-lock.json o npm-shrinkwrap.json | Senza uno dei due, il comando non è quello descritto |
Se il lock non coincide con package.json, esce con errore | Non aggiorna il lock per farli tornare |
| Installa solo l’intero progetto | Non si aggiunge una dipendenza singola con questo comando |
Se node_modules c’è, lo rimuove prima di installare | Non è un incremento sulla cartella già presente |
Non scrive package.json né i package-lock | La pagina dice: le installazioni sono «essentially frozen» |
C’è una nota accanto. Se il lock è nato da npm install con flag che cambiano l’albero, per esempio --legacy-peer-deps o --install-links, gli stessi flag vanno passati a npm ci, altrimenti gli errori sono probabili. La pagina suggerisce di fissarli in un .npmrc di progetto, con npm config set … --location=project, e di committare quel file. Non è un flag decorativo.
Gli alias stampati sulla stessa pagina sono clean-install, ic, install-clean e isntall-clean. L’ultimo è scritto così, con la t mancante. Non lo correggo: è nella lista ufficiale. Il parallelo con composer install e composer update è solo questo: due comandi vicini non fanno la stessa scrittura sul file di lock.
Quando install riscrive il lock
La pagina di npm install, stessa etichetta di versione, descrive il caso senza argomenti. npm confronta package.json e package-lock.json. Se le versioni risolte nel lock soddisfano i range del json, usa le versioni esatte del lock. Se i range non coincidono, risolve versioni nuove che soddisfano package.json e aggiorna package-lock.json. L’esempio sulla pagina è modificare un range, per esempio ^7.0.0.
È il punto in cui i due comandi si separano. npm ci, sulla sua pagina, in quel disallineamento esce con errore. npm install, sulla sua, aggiorna il lock. Mettere npm ci in una pipeline e npm install sul portatile non è lo stesso gesto ripetuto due volte.
yarn.lock non è nella lista di ci
La pagina di install dice che, se esistono un package-lock, uno shrinkwrap o un yarn lock, l’installazione delle dipendenze segue quell’ordine: prima npm-shrinkwrap.json, poi package-lock.json, poi yarn.lock. La pagina di npm ci non nomina yarn.lock tra i file che il progetto «must» avere. Nomina solo package-lock o shrinkwrap. Non deduco che npm ci legga yarn.lock: la pagina che ho letto non lo scrive.
Errori da evitare
Lanciare
npm ciper aggiungere un pacchetto. La pagina dice che il comando installa solo l’intero progetto.Aspettarsi che
npm cisistemi un lock vecchio. Il disallineamento, lì, è un errore. Chi aggiorna il lock, sulla pagina gemella, ènpm install.Credere che
node_modulesvenga riusato. Se c’è,npm cilo cancella prima.Omettere su
npm cii flag con cui è stato generato il lock. La nota cita--legacy-peer-depse--install-links.Trattare
yarn.lockcome sostituto del package-lock pernpm ci. Non è nella lista dei file obbligatori di quella pagina.
In sintesi
Sulle docs npm etichettate Version 11.21.0 (Legacy), il 20 ottobre 2026, npm ci è un’installazione congelata: lock o shrinkwrap già presenti, niente scritture, errore se non coincidono, node_modules rimosso, niente dipendenze singole. npm install senza argomenti, se i range non tornano, aggiorna package-lock.json. L’alias isntall-clean è stampato così. Non ho eseguito i due comandi su un progetto.
Foto di copertina: Solijon Solayev, aggiornamento di Arch Linux con pacman su un portatile Acer, Wikimedia Commons, CC BY-SA 4.0. È pacman, non npm ci, e non è un diagramma del lockfile.
