Tecnología · GUÍA PRÁCTICA
¿npm ci dice que package-lock no está sincronizado? Audite el manifiesto, los flags y la versión antes de regenerar
Conserve primero las entradas que fallan. El mismo EUSAGE puede significar deriva de dependencias, configuración distinta, un lockfile antiguo o un resolver específico de la versión de npm.
Cuando npm ci informa que package.json y package-lock.json no están sincronizados, se niega a reescribir un árbol que debería estar congelado. El mensaje indica un fallo de coherencia, no una causa universal. Conserve las entradas, demuestre qué cambió y solo entonces decida si debe corregir el manifiesto, la configuración, la versión de npm o el lockfile generado.
No empiece borrando package-lock.json, cambiando CI a npm install ni añadiendo --force. Puede destruir la comparación que explica el fallo y convertir una edición pequeña en un cambio masivo del árbol. Una reparación segura explica la entrada Missing o Invalid, se reproduce con la política prevista y deja un diff revisable.
1. Leer EUSAGE como una barrera de coherencia
npm ci está diseñado para instalaciones automatizadas y reproducibles. Requiere lockfile, elimina node_modules antes de instalar y no escribe package.json ni el lockfile. Si difieren, termina para impedir que CI acepte un árbol no revisado.
Copie el error completo antes de probar otro comando. Conserve cada línea Missing o Invalid, el directorio y si se ejecutó en la raíz o en un workspace. El primer paquete y rango suelen elegir la rama; la sugerencia genérica de npm install no prueba que regenerar sea la única reparación.
2. Crear un registro de manifiesto, lockfile y entorno
Anote el commit y si package.json o package-lock.json están modificados. Revise dependencies, devDependencies, optionalDependencies, peerDependencies, bundledDependencies, overrides y workspaces. Registre lockfileVersion y examine packages[""] y la ruta citada; no edite a mano integrity ni campos generados.
Registre node --version, npm --version, el .npmrc del proyecto, variables relevantes y el comando exacto de CI. Incluya legacy-peer-deps, strict-peer-deps, install-links, omit/include y selectores de workspace. Oculte tokens y credenciales: es un registro comparativo, no un volcado de secretos.
3. Separar deriva intencionada de una edición accidental
Si package.json cambió después del lockfile, determine si la edición fue intencionada y revisada. Una dependencia directa nueva ausente de packages[""].dependencies es deriva del manifiesto. Overrides, miembros del workspace o configuración también pueden cambiar el árbol aunque el bloque dependencies parezca igual.
Si el cambio es intencionado, regenere con la versión y configuración previstas en un entorno controlado. Si fue accidental, restaure el manifiesto revisado. No haga que CI repare el árbol en cada ejecución: el lockfile generado es un cambio de código que necesita diff y responsable.
4. Reproducir la política que creó el lockfile
La guía oficial advierte que un lockfile creado con opciones que moldean el árbol debe instalarse con las mismas opciones; legacy-peer-deps es un ejemplo. La configuración común debe estar en el .npmrc del proyecto, no depender silenciosamente de ajustes personales.
Compare un checkout limpio con la misma versión mayor de npm, .npmrc y comando de workspace. Si solo funciona añadiendo un flag, documente por qué pertenece a la política antes de guardarlo. Un comando exitoso sin política puede trasladar el fallo a otra máquina.
5. Distinguir comportamiento de versión y lockfile dañado
Si manifiesto, lockfile y configuración son idénticos pero el resultado cambia con npm, reproduzca una matriz pequeña antes de escribir archivos. Guarde los errores de la versión soportada y una adyacente. Casos upstream recientes donde npm install termina pero npm ci rechaza el árbol son pruebas para escalar, no permiso para ignorar la barrera.
Un lockfile realmente dañado u obsoleto necesita pruebas: error de parseo, metadatos raíz ausentes, referencias imposibles, marcadores de conflicto o transición conocida. Conserve el original, regenere una vez con el toolchain previsto y compare todo el diff; cambios ajenos indican que el entorno aún no está controlado.
6. Verificar la corrección mínima desde un checkout limpio
Tras la corrección mínima, parta de un checkout limpio. Use las versiones previstas, solo la configuración guardada y el mismo npm ci que CI. Confirme que el lockfile no cambia, el workspace correcto se instala, los scripts se comportan como se espera y pasan las pruebas o el build existentes.
Revise el diff del lockfile como código: rangos raíz, versiones resueltas, integrity, relaciones peer y eliminaciones deben corresponder al cambio. Si falla otra vez, conserve el nuevo error y vuelva a la rama; no regenere repetidamente hasta que pase por casualidad.
