En macOS, primero identifique si npm informa un conflicto de fusión de Git, una discrepancia entre package.json y package-lock.json, o un error de resolución de dependencias de pares. Compruebe los archivos del proyecto, el estado de Git y las versiones de npm en Terminal antes de modificar nada. Si solo es necesario conciliar el lockfile, la opción --package-lock-only de npm puede actualizarlo sin reinstalar paquetes en node_modules.

Comience en la carpeta del proyecto y preserve el estado actual

Abra Terminal, vaya al directorio del proyecto y confirme que se encuentra en la raíz prevista del proyecto. En Finder, puede localizar la carpeta y luego usar el comando cd de Terminal; si la ruta contiene espacios, escríbala entre comillas, por ejemplo cd "$HOME/Projects/My App". Ejecute:

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

git status --short muestra si alguno de los manifiestos tiene modificaciones sin confirmar. Si hay cambios que necesita conservar, guárdelos o confírmelos antes de continuar; no sobrescriba archivos mientras aún esté decidiendo qué cambios de dependencias corresponden. Registre las versiones de Node.js y npm para poder compararlas con la configuración documentada del proyecto o la configuración de integración continua. Los formatos de los lockfiles de npm han cambiado a lo largo de las versiones principales de npm, por lo que una diferencia de formato puede explicar discrepancias inesperadas sin demostrar que las dependencias en sí estén defectuosas. Documentación de package-lock de npm

Determine qué tipo de conflicto tiene

Si package-lock.json contiene marcas de Git como <<<<<<<, ======= o >>>>>>>, se trata de un conflicto de fusión en el control de versiones. Inspeccione las secciones completas afectadas y compare los cambios de ambas ramas. Resuelva primero las declaraciones de dependencias en package.json: la guía anterior de npm para conflictos en el lockfile indica explícitamente resolver manualmente los conflictos del manifiesto antes de regenerar el lockfile. No conserve simplemente un lado del lockfile por costumbre; es posible que cada rama haya añadido o cambiado dependencias. Guía de conflictos de package-lock de npm

Si no hay marcas de Git, compare los nombres y rangos de las dependencias en package.json con el lockfile. package.json especifica los rangos aceptables, mientras que el lockfile registra un árbol de dependencias resuelto. La documentación actual de npm indica que un comando npm install normal usa las versiones bloqueadas cuando satisfacen los rangos del manifiesto y actualiza el lockfile cuando no lo hacen. Cómo usa un lockfile npm install

Si el comando falla con un mensaje de dependencias de pares, concéntrese en los paquetes mencionados en ese error y en sus requisitos de pares. Podría tratarse de una incompatibilidad válida entre los rangos de paquetes declarados y no de una instalación corrupta. No utilice --force ni --legacy-peer-deps como atajo de diagnóstico: alterar el comportamiento de resolución de dependencias puede generar un árbol que difiera de la configuración prevista para el proyecto.

Inspeccione los cambios antes de pedir a npm que concilie

Revise el historial del proyecto y el diff actual:

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

Busque el commit o la rama que modificó la declaración de dependencias, la versión del lockfile o la configuración de npm. Compruebe también si el proyecto cuenta con un .npmrc; npm documenta que las opciones que modelan el árbol, como legacy-peer-deps o install-links, pueden influir en si un lockfile y una instalación limpia posterior coinciden. Utilice la misma configuración específica del proyecto ya adoptada por el repositorio en lugar de agregar nuevas opciones al azar. Documentación de npm ci

El valor lockfileVersion ayuda a identificar el formato del archivo, pero evite considerarlo un diagnóstico por sí solo. npm documenta las versiones de formato 1, 2 y 3 y señala que las versiones más recientes de npm pueden actualizar lockfiles antiguos. Un cambio en la versión puede reflejar el comportamiento de compatibilidad de npm; inspeccione el diff real de dependencias antes de aceptar una reescritura de gran escala. Formato del lockfile y archivos más antiguos

Concilie el lockfile sin reinstalar las dependencias

Tras resolver las marcas de conflicto y asegurarse de que package.json sea correcto, pida a npm que actualice únicamente el lockfile:

npm install --package-lock-only

npm documenta esta opción como la actualización de package-lock.json sin comprobar node_modules ni descargar dependencias. Se trata de un paso de conciliación específico; no garantiza que el conjunto resultante de dependencias sea el deseado, así que revise el diff después. Opciones de npm install

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

git diff --check ayuda a detectar errores en los espacios en blanco, mientras que el diff en sí muestra lo que npm modificó. Confirme que el manifiesto no haya incorporado cambios imprevistos, inspeccione modificaciones inesperadas de versiones o una reescritura amplia del lockfile, y compruebe que hayan desaparecido las marcas de conflicto. Si los cambios propuestos no tienen sentido, restaure los archivos desde su estado guardado o desde el control de versiones y reexamine la causa en lugar de eliminar node_modules o regenerarlo todo.

Sepa cuándo es adecuado realizar una instalación limpia

Utilice npm ci únicamente después de que el manifiesto y el lockfile se hayan alineado intencionadamente y desee reproducir el árbol de dependencias bloqueado. Requiere un lockfile, falla en lugar de actualizar una discrepancia y elimina un directorio node_modules existente antes de instalar. Esto lo hace útil para confirmar un estado resuelto, pero no es un comando de inspección inofensivo. Comportamiento de npm ci

Si npm install --package-lock-only no puede resolver el conflicto, registre el error exacto, revise los rangos de paquetes indicados y los parámetros de npm del proyecto, y compárelos con la rama o el entorno de CI que generó el lockfile. La cuestión decisiva es qué declaraciones de dependencias debe conservar el proyecto; una limpieza de la instalación no resolverá eso por usted. Una vez que esa decisión quede reflejada en package.json, regenere solo el lockfile, inspeccione el cambio propuesto y entonces decida si es necesaria una instalación limpia.

Fuentes