Tutoriales de VPS
npm ERESOLVE en VPS: peers, npm ci y lockfile (2026)
Lee el conflicto, elige versiones compatibles y revisa el lock. Instala en limpio y valida la aplicación antes de publicar.

Desplegar Node.js, Next.js o un proyecto de un agente puede detenerse cuando npm install muestra ERESOLVE unable to resolve dependency tree. npm no logra formar un árbol aceptable; revisa compatibilidad entre peerDependencies del plugin y su biblioteca anfitriona.
Lee versión encontrada y rango solicitado, y haz el cambio mínimo. Conserva package-lock.json y evita --force como opción predeterminada. Instalar correctamente no demuestra compatibilidad en ejecución.
Los ejemplos usan npm 11; la revisión original data del 16 de octubre de 2026. Consulta tu versión y repara en rama de desarrollo, builder o nuevo directorio, fuera de las dependencias en servicio.
| Log | Investigar | Evitar inicialmente |
|---|---|---|
ERESOLVE, Could not resolve dependency, peer | Rangos, origen y configuración | Cambiar espejo/caché repetidamente |
EAI_AGAIN, ETIMEDOUT | DNS, red, proxy, registry | Cambiar peers |
EBADENGINE o engines | Versiones Node/npm | Suponer conflicto peer |
EACCES | Usuario/permisos | Instalar todo con sudo |
Killed, heap | Memoria y límites | Actualizar paquetes para reparar memoria |
Pueden aparecer fallos sucesivos; sigue la fase real. Si instalar funciona y build muere, consulta OOM Next.js.
El ejemplo selecciona React 17 y React DOM exige React 18:
Found: [email protected]
Could not resolve dependency:
peer react@"^18.2.0" from [email protected]
Extrae:
- Anfitrión elegido:
[email protected]. - Rango:
[email protected]necesitareact@^18.2.0. - Solicitante: determina si
react-domes directo o transitivo.
Otra descarga no lo resuelve automáticamente. peerDependencies declara compatibilidad plugin/anfitrión. Desde v7 npm instala peers por defecto y puede rechazar restricciones imposibles; consulta peerDependencies. React 17/18 reproduce restricciones históricas, no recomendaciones para 2026. Elige según soporte, mantenimiento de seguridad y pruebas.
Desde la raíz correcta recoge estas comprobaciones de lectura en local, CI, build Docker y VPS:
pwd
git status --short
node --version
npm --version
npm pkg get engines packageManager
npm config get registry
npm config get legacy-peer-deps
npm config get strict-peer-deps
npm config get omit
- Compara commit,
package.jsony lockfile. - Comprueba Node/npm frente a proyecto, equipo e imagen.
- Identifica el flujo npm/pnpm/Yarn original.
- Revisa diferencias de
legacy-peer-deps=trueentre local y servidor. - Consulta
NODE_ENV=productiony configuración npm del entorno CI.
packageManager no obliga a todos los sistemas a cambiar herramientas. Lee logs antes de actualizar npm globalmente. Configuración de proyecto/usuario/global, CLI y entorno influyen; usuarios SSH y despliegue pueden diferir. Consulta .npmrc. Comparte solo ajustes necesarios sin credenciales, no archivos completos con tokens.
Usa la versión del error, siguiendo el ejemplo histórico:
npm view [email protected] peerDependencies engines --json
npm view [email protected] engines --json
Un npm view react-dom peerDependencies sin versión puede describir latest y no el paquete antiguo. npm view lee metadata; consulta npm view. Para privados, usa su registry, sin enviar nombres a servicios ajenos.
Si hay instalación, rastrea el origen:
npm explain react
npm ls react react-dom --all
npm explain explica paquetes instalados. Sin instalación completa o node_modules, puede ser parcial: consulta error, package.json raíz, workspaces y lock. Consulta npm explain. npm ls puede devolver no cero por invalid/missing: conserva la prueba. Consulta npm ls.
| Opción | Cuándo | Validar |
|---|---|---|
| Actualizar plugin, mantener anfitrión | Existe versión mantenida compatible | API, configuración y función |
| Cambiar anfitrión y complementos | Migración aceptable | Requisitos, build y negocio |
| Sustituir plugin abandonado | Sin versión compatible | Función, datos y configuración |
| Excepción temporal existente | Historia, pruebas y salida documentadas | CI, riesgos y retirada |
No bajes el framework por un solo peer: la aplicación y otros plugins pueden exigir APIs nuevas. Busca rangos compatibles comunes.
Este package.json crea conflicto en un proyecto aislado de demostración; no reemplaces el real:
{
"name": "vps-eresolve-proof",
"version": "1.0.0",
"private": true,
"dependencies": {
"react": "17.0.2",
"react-dom": "18.2.0"
}
}
En el directorio de ejemplo, ejecuta:
npm install --package-lock-only --ignore-scripts
Solo allí cambia dependencies.react a 18.2.0, conserva react-dom en 18.2.0 y ejecuta:
npm install --package-lock-only --ignore-scripts
npm ci --ignore-scripts
npm ls react react-dom --depth=0
El artículo original informa de una prueba temporal independiente con Node.js 24.21.0 / npm 11.19.0: ERESOLVE antes; lock y npm ci correctos después; ambos directos en 18.2.0; npm ci no reescribió el lock.
La comprobación histórica desactivó scripts de ciclo de vida y solo acredita el árbol de ejemplo. El proyecto real necesita scripts, build y funciones; --ignore-scripts no es despliegue completo. Consulta npm install.
Corrige package.json y lock en un entorno revisable. Despliega declaraciones, lock y ajustes verificados con instalación limpia.
npm ci exige lock y falla si no coincide; no repara ni escribe package.json o lock, y elimina primero node_modules. Consulta npm ci.
- Ejecútalo fuera del directorio activo para no reemplazar dependencias en servicio.
- Corrige discrepancias en el build, sin improvisar npm install en producción.
- Un árbol peer incompatible también puede fallar con npm ci.
Revisa el diff real:
git diff -- package.json package-lock.json
Versiona el lock. Cambios ajenos masivos exigen revisar versión/configuración npm y borrado accidental. Consulta package-lock.json. En workspaces, gestiona lock compartido desde la raíz acordada, no otro inutilizado en un subdirectorio.
| Opción | Efecto | ¿Demuestra compatibilidad? |
|---|---|---|
--legacy-peer-deps | Ignora peers al diseñar árbol | No |
--force | Relaja varias protecciones, incluidos peers raíz | No; afecta más cosas |
--omit=peer | No despliega peers al disco, pero calcula árbol válido | No elude conflictos |
Consulta npm Config. Corrige versiones; sugerir un flag en un error no lo convierte en política global.
Una excepción legacy necesita motivo, combinación, pruebas y retirada. Flags que forman el árbol suelen necesitar coherencia en CI. Guarda política no secreta revisada en .npmrc, sin tokens. Quitar el flag conservando lock antiguo no demuestra modo estricto: valida resolución e instalación limpia.
Selecciona versiones otra vez, evitando quizá un conflicto y añadiendo actualizaciones ajenas. Conserva el original y revisa el diff en desarrollo.
No. overrides cambia selección, no compatibilidad API ni rangos arbitrarios. Revisa alcance/límites directos en overrides y prueba aplicación.
No ante un conflicto explícito. Solo investiga integridad/metadata con pruebas; consulta npm cache.
omit controla disco, no descarta toda resolución. El build puede necesitar TypeScript/bundler; distingue construcción y ejecución.
Cadena completa, rangos compatibles, diff mínimo e instalación limpia sin bypass; después build, tipos y funciones existentes. Si queda excepción, necesita impacto y salida.
- Registra Node/npm, commit y resolución reales.
- Instalación limpia sin invalid/missing inexplicados.
- Build, checks y negocio existentes pasan; el ejemplo no sustituye validación real.
- Declaraciones, lock y configuración no secreta revisados, explicando cambios ajenos.
- Prepara release/CI nuevo, valida salud antes de cambiar y conserva artefacto/lock anterior.
- Revierte código, dependencias y configuración juntos, no solo package.json dejando node_modules nuevos.
El objetivo es una aplicación compatible reproducible, más allá de desaparecer ERESOLVE.