Sur macOS, déterminez d'abord si npm signale un conflit de fusion Git, une incohérence entre package.json et package-lock.json, ou une erreur de résolution de dépendance de pair (peer dependency). Vérifiez les fichiers du projet, l'état Git et les versions de npm dans le Terminal avant de modifier quoi que ce soit. Si seul le lockfile doit être réconcilié, l'option --package-lock-only de npm permet de le mettre à jour sans réinstaller les paquets dans node_modules.

Commencez dans le dossier du projet et préservez l'état actuel

Ouvrez le Terminal, déplacez-vous dans le répertoire du projet et confirmez que vous êtes bien à la racine souhaitée du projet. Dans le Finder, vous pouvez localiser le dossier, puis utiliser la commande cd du Terminal ; si le chemin contient des espaces, mettez-le entre guillemets, par exemple cd "$HOME/Projects/My App". Exécutez :

pwd
git status --short
node --version
npm --version

git status --short indique si l'un des manifestes comporte des modifications non validées. Si vous devez conserver certaines modifications, enregistrez-les ou validez-les avant de poursuivre ; n'écrasez pas de fichiers tant que vous êtes encore en train de décider des modifications de dépendances à conserver. Notez les versions de Node.js et de npm afin de pouvoir les comparer avec la configuration documentée du projet ou la configuration de l'intégration continue. Les formats de lockfile npm ont évolué au fil des versions majeures de npm, de sorte qu'une différence de format peut expliquer des remaniements inattendus sans prouver que les dépendances elles-mêmes sont corrompues. Documentation npm sur package-lock

Déterminez le type de conflit auquel vous faites face

Si package-lock.json contient des marqueurs Git tels que <<<<<<<, ======= ou >>>>>>>, il s'agit d'un conflit de fusion de contrôle de version. Inspectez l'intégralité des sections concernées et comparez les modifications des deux branches. Résolvez d'abord les déclarations de dépendances dans package.json : les anciennes instructions de npm concernant les conflits de lockfile indiquent explicitement de résoudre manuellement les conflits de manifeste avant de régénérer le lockfile. Ne conservez pas simplement une version du lockfile par habitude ; chaque branche a pu ajouter ou modifier des dépendances. Conseils de npm sur les conflits de package-lock

S'il n'y a pas de marqueurs Git, comparez les noms de dépendances et les plages de versions dans package.json avec le lockfile. package.json spécifie les plages acceptables, tandis que le lockfile enregistre un arbre de dépendances résolu. La documentation actuelle de npm indique qu'un npm install standard utilise les versions verrouillées lorsqu'elles satisfont aux plages du manifeste et met à jour le lockfile lorsqu'elles ne les satisfont pas. Comment npm install utilise un lockfile

Si la commande échoue avec un message relatif aux dépendances de type peer, concentrez-vous sur les paquets nommés dans cette erreur et sur leurs exigences de pairs. Il peut s'agir d'une incompatibilité réelle entre les plages de paquets déclarées, et non d'une installation corrompue. N'utilisez pas --force ou --legacy-peer-deps comme raccourci de diagnostic : modifier le comportement de résolution des dépendances peut générer un arbre différent de la configuration prévue pour le projet.

Inspectez les modifications avant de demander à npm de réconcilier

Passez en revue l'historique du projet et le diff actuel :

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

Recherchez le commit ou la branche qui a modifié la déclaration de dépendance, la version du lockfile ou la configuration de npm. Vérifiez également si le projet dispose d'un fichier .npmrc ; npm indique dans sa documentation que des options modifiant l'arbre, telles que legacy-peer-deps ou install-links, peuvent affecter la cohérence entre un lockfile et une future installation propre. Utilisez les mêmes paramètres spécifiques au projet déjà adoptés par le dépôt plutôt que d'ajouter de nouvelles options au hasard. Documentation de npm ci

La valeur lockfileVersion aide à identifier le format du fichier, mais évitez de la considérer comme un diagnostic à elle seule. npm documente les versions de format 1, 2 et 3 et indique que les versions plus récentes de npm peuvent mettre à jour d'anciens lockfiles. Une version modifiée peut refléter le comportement de compatibilité de npm ; inspectez le diff réel des dépendances avant d'accepter une réécriture majeure. Format du lockfile et fichiers plus anciens

Réconciliez le lockfile sans réinstaller les dépendances

Après avoir résolu les marqueurs de conflit et corrigé package.json, demandez à npm de mettre à jour uniquement le lockfile :

npm install --package-lock-only

npm documente cette option comme mettant à jour package-lock.json sans vérifier node_modules ni télécharger de dépendances. Il s'agit d'une étape de réconciliation ciblée ; elle ne garantit pas que l'ensemble des dépendances obtenu correspond à celui souhaité, examinez donc le diff par la suite. Options de npm install

git diff --check
git diff -- package.json package-lock.json
git status --short

git diff --check aide à détecter les erreurs d'espacement, tandis que le diff lui-même montre ce que npm a modifié. Confirmez que le manifeste n'a pas subi de modifications involontaires, inspectez les changements de version inattendus ou une réécriture globale du lockfile, et vérifiez que les marqueurs de conflit ont disparu. Si les modifications proposées ne semblent pas cohérentes, restaurez les fichiers à partir de votre état sauvegardé ou du contrôle de version et réexaminez la cause au lieu de supprimer node_modules ou de tout régénérer.

Sachez quand une installation propre est appropriée

Utilisez npm ci uniquement après avoir délibérément aligné le manifeste et le lockfile et lorsque vous souhaitez reproduire l'arbre de dépendances verrouillé. Cette commande nécessite un lockfile, échoue au lieu de corriger une incohérence, et supprime un répertoire node_modules existant avant l'installation. Cela la rend utile pour confirmer un état résolu, mais ce n'est pas une commande d'inspection sans conséquence. Comportement de npm ci

Si npm install --package-lock-only ne parvient pas à résoudre le conflit, relevez l'erreur exacte, examinez les plages de paquets mentionnées ainsi que les paramètres npm du projet, et comparez-les avec la branche ou l'environnement CI qui a généré le lockfile. La question décisive est de savoir quelles déclarations de dépendances le projet doit conserver ; un nettoyage de l'installation ne peut pas trancher pour vous. Une fois cette décision prise et appliquée dans package.json, régénérez uniquement le lockfile, inspectez les modifications proposées, puis déterminez si une installation propre est nécessaire.

Sources