Tous les articles

Infra9 min de lecture

Ne sous-estime pas le lock file : npm ci, conflits, sécurité

Ce que font vraiment package-lock.json, yarn.lock et pnpm-lock.yaml, pourquoi les commiter, npm ci ou npm install, le hash d'intégrité et comment résoudre un conflit.

Aussi en Português, English, Español

Si tu utilises npm, Yarn ou pnpm, tu as déjà vu un package-lock.json, un yarn.lock ou un pnpm-lock.yaml dans le projet. Beaucoup de gens l'ignorent, le suppriment quand il y a un conflit ou ne le commitent même pas.

C'est une grosse erreur, et dans cet article je te montre pourquoi avec des exemples que j'ai vraiment lancés, pas seulement avec de la théorie.

J'ai publié la première version de cet article sur Medium en septembre 2025, en portugais. Voici la version revue, avec des tests, npm ci (qui manquait dans l'original), la bonne façon de résoudre un conflit et une correction sur ce que le hash d'intégrité protège et ce qu'il ne protège pas.

Le classique « ça marche sur ma machine » : même package.json, versions différentes

TL;DR#

  • Le package.json accepte des plages de versions (^2.0.0 veut dire « n'importe quelle 2.x »). Le lock file garde la version exacte qui a été installée, pour chaque dépendance et pour leurs dépendances.
  • Sans le lock, le même package.json installe des versions différentes selon les jours. Dans mon test, j'ai eu 2.1.1 avec le lock et 2.1.3 sans.
  • Commite le lock file et ne le supprime jamais pour « régler » un problème.
  • En CI, utilise npm ci (ou pnpm install --frozen-lockfile, ou yarn install --immutable). Il installe exactement ce qu'il y a dans le lock et échoue si le lock n'est pas à jour.
  • Le hash d'intégrité garantit que le paquet est le même que celui qui a été verrouillé, octet par octet. Il ne dit pas si le paquet est sûr, mais il empêche une nouvelle version, peut-être malveillante, d'entrer sans que personne ne le voie.
  • Conflit dans le lock : résous le package.json et relance npm install. npm refait le lock tout seul.
  • Un projet, un gestionnaire. Mélanger npm et Yarn crée deux locks qui ne sont pas d'accord.

Ce que fait le lock file#

Dans le package.json, tu écris rarement une version exacte. Par défaut, npm install enregistre une plage :

{
  "dependencies": {
    "ms": "^2.0.0"
  }
}

Le ^2.0.0 veut dire « n'importe quelle version 2.x à partir de la 2.0.0 ». Aujourd'hui, ça peut être la 2.1.1. Demain, si une 2.1.4 sort, ce sera elle. Et ça vaut aussi pour chaque dépendance de tes dépendances.

Le lock file règle ça : il garde la version exacte qui a été installée, d'où elle vient et un hash du fichier. Voici l'entrée de ms dans le package-lock.json de mon test :

"node_modules/ms": {
  "version": "2.1.1",
  "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
  "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg..."
}

Le test : le même package.json, deux versions#

J'ai monté un projet avec ms verrouillé en 2.1.1 et le package.json qui accepte ^2.0.0. Ensuite, j'ai installé deux fois : une fois avec le lock, une autre en copiant seulement le package.json dans un nouveau dossier.

$ npm ci && node -p "require('ms/package.json').version"
2.1.1
 
# same package.json, no lock file
$ npm install && node -p "require('ms/package.json').version"
2.1.3
La plage du package.json accepte plusieurs versions. Le lock en choisit une et n'en change plus

C'est exactement le « ça marche sur ma machine » : la personne qui a installé il y a six mois a une version, celle qui a cloné aujourd'hui en a une autre, et le bug n'apparaît que chez l'une des deux. Avec le lock commité, les deux installent la même chose.

npm install ou npm ci ?#

Les deux installent des dépendances, mais avec des objectifs différents :

  • npm install respecte le lock tant qu'il correspond au package.json, mais peut mettre à jour le lock : si tu as ajouté un paquet ou changé une plage, il résout à nouveau et réécrit le fichier. C'est la commande du quotidien, quand tu veux changer de dépendances.
  • npm ci supprime le node_modules et installe exactement ce qu'il y a dans le lock. Il ne modifie jamais le lock. Si le package.json et le lock ne correspondent pas, il s'arrête avec une erreur :
npm error code EUSAGE
npm error `npm ci` can only install packages when your package.json and package-lock.json
or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install`
before continuing.

Cette erreur est là pour t'aider : quelqu'un a modifié le package.json et a oublié de commiter le lock. Mieux vaut que la CI casse plutôt que de partir en production avec des versions que personne n'a testées.

Règle pratique : npm install sur ta machine quand tu veux changer de dépendances ; npm ci en CI, dans Docker et chaque fois que tu veux juste installer ce que le projet définit déjà.

Les autres gestionnaires ont l'équivalent :

GestionnaireLock fileInstaller sans toucher au lock
npmpackage-lock.jsonnpm ci
pnpmpnpm-lock.yamlpnpm install --frozen-lockfile
Yarn (2 ou plus récent)yarn.lockyarn install --immutable
Yarn 1yarn.lockyarn install --frozen-lockfile

Avec pnpm et le Yarn moderne, ce mode est déjà le comportement par défaut quand ils détectent qu'ils tournent dans une CI.

Le hash d'intégrité#

Chaque paquet du lock a un champ integrity, un hash SHA-512 du fichier téléchargé. À l'installation, npm calcule le hash de ce qui est arrivé et compare. Pour voir ça en action, j'ai remplacé le hash de ms dans le lock par un faux :

$ npm ci
npm error code EINTEGRITY
npm error sha512-AAAA...== integrity checksum failed when using sha512:
wanted sha512-AAAA...== but got sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg...

npm a refusé d'installer. L'original de cet article disait que ce hash « empêche l'installation de bibliothèques malveillantes », et ça mérite une correction. Le hash garantit que le paquet est exactement le même que celui qui a été verrouillé. Si la version verrouillée était déjà malveillante, le hash correspondrait quand même.

La vraie protection est ailleurs : avec le lock et npm ci, une nouvelle version n'entre pas sans que quelqu'un la demande. Le 8 septembre 2025, une semaine après l'original de cet article, le compte d'un mainteneur a été piraté et des versions malveillantes de paquets très utilisés, comme chalk@5.6.1 et debug@4.4.2, sont restées sur npm pendant environ deux heures. Un projet avec une plage ^ et sans lock, qui installait pendant ce créneau, pouvait récupérer la version infectée. Un projet avec le lock verrouillé sur une version antérieure et qui installait avec npm ci gardait la version d'avant.

Le lock ne sait pas si un paquet est sûr. Il ne laisse simplement pas entrer une nouvelle version sans que quelqu'un la demande

Bonnes pratiques#

1. Commite le lock file#

Il fait partie du projet, comme le package.json. S'il n'est pas dans Git, chaque personne et chaque build résout les plages à nouveau et peut tomber sur des versions différentes. La seule exception courante, c'est quand tu publies une bibliothèque sur npm : son lock ne suit pas dans le projet de la personne qui l'installe. Même là, ça vaut le coup de le commiter, pour que ta propre CI soit reproductible.

2. Ne supprime pas le lock pour régler un problème#

Supprimer le lock et lancer npm install ne « nettoie » rien : ça met à jour toutes les dépendances d'un coup, même celles qui n'avaient rien à voir avec le problème. Si quelque chose a cassé, tu as échangé un bug contre vingt changements que personne n'a relus. Comprends d'abord l'erreur. Si tu dois mettre à jour un paquet, mets à jour ce paquet.

3. Conflit dans le lock : laisse le gestionnaire le résoudre#

Deux branches ont ajouté des dépendances différentes, et le merge a donné un conflit dans le package.json et dans le lock. Résoudre le lock à la main, ligne par ligne, c'est chercher les erreurs. La bonne façon :

  1. résous à la main le conflit du package.json (il est court et lisible) ;
  2. lance npm install.

npm comprend les marqueurs de conflit dans le package-lock.json et refait le fichier en combinant les deux côtés (testé avec npm 11). Dans mon test, une branche a ajouté left-pad et l'autre is-number. Après avoir réuni les deux dans le package.json et lancé npm install, le lock n'avait plus aucun marqueur de conflit et contenait les deux paquets :

$ git merge feat-a
CONFLICT (content): Merge conflict in package-lock.json
CONFLICT (content): Merge conflict in package.json
 
# fix package.json by hand, then:
$ npm install
added 1 package, and audited 4 packages in 395ms

Ensuite, vérifie le diff du lock avant de commiter. Il ne doit montrer que les paquets des deux branches.

4. Un projet, un gestionnaire#

Si le projet a un package-lock.json, utilise npm. S'il a un pnpm-lock.yaml, utilise pnpm. Lancer yarn dans un projet npm crée un yarn.lock qui ne sait rien du package-lock.json, et les deux commencent à se contredire sur les versions.

Pour que ce soit explicite, déclare le gestionnaire dans le package.json. pnpm et Yarn lisent ce champ :

{
  "packageManager": "pnpm@10.0.0"
}

5. Mets à jour exprès#

Tu veux mettre à jour ? Utilise la commande du gestionnaire, et de préférence un paquet à la fois :

npm outdated            # what is behind
npm update ms           # update within the package.json range
npm install ms@latest   # jump to the latest version (may change the range)

Le lock change en même temps, et le diff montre exactement ce qui a changé. Des outils comme Dependabot et Renovate le font pour toi, en ouvrant une PR par mise à jour.

Résumé#

  • Le package.json dit quelles versions conviennent ; le lock dit quelle version a été installée.
  • Commite le lock et ne le supprime pas pour « régler » un problème.
  • npm ci en CI et dans Docker, npm install quand tu veux changer de dépendances.
  • Le hash garantit que le paquet n'a pas changé ; le lock garantit qu'une nouvelle version n'entre pas sans PR.
  • Conflit dans le lock : résous le package.json et lance npm install.
  • Un gestionnaire par projet.

Le lock file n'est pas une corvée : c'est lui qui garantit que le code testé est bien le code qui part en production.

Références#

  • Infra
  • npm
  • pnpm
  • yarn
  • lock file
  • ci
  • sécurité

Écrit par

Ingénieure logiciel et designer. J'écris sur ce que je rencontre en créant des apps, des APIs et des produits.