Base de conocimientos
Solución de problemas de Zinnector®
Los errores con los que realmente se tropieza la gente al usar el Zinnector CLI y la solución para cada uno: spawn EINVAL en Windows, el aviso EBADENGINE de npm, node-gyp pidiendo Visual Studio en Node 26, EPERM durante la instalación, un tiempo de ejecución que no arranca y un puerto en uso.
Los errores que las personas realmente experimentan con la CLI de Zinnector®, qué significa cada uno y su solución. Cada entrada menciona el texto exacto que verá, para que pueda buscarlo en esta página. Si el suyo no se encuentra aquí, ejecute el comando fallido con ZINNECTOR_DEBUG=1 y abra una incidencia en github.com/Zinn-Digital/zinnector/issues con la salida, su node --version y su sistema operativo.
"spawn EINVAL" justo después de aceptar la instalación del entorno de ejecución (Windows)
Un error en Zinnector® 0.1.0 y 0.1.1. En Windows, el instalador del entorno de ejecución ejecutó npm.cmd por su nombre, y Node se ha negado a generar un archivo .cmd sin un intérprete de comandos desde su corrección para CVE-2024-27980, por lo que la instalación falló un segundo después de que usted respondiera Y. Solucionado en 0.1.2: npm ahora se ejecuta como node npm-cli.js, que es el mismo en todas las plataformas y no necesita un intérprete de comandos. Ejecute npm install -g zinnector@latest y luego zinnector dev nuevamente.
"npm WARN EBADENGINE" durante la instalación, o "Zinnector® needs Node 24 or newer"
Su versión de Node es anterior a la 24. npm muestra la advertencia porque el paquete declara engines: >=24.18.1; la instalación se completa de todos modos, pero zinnector se niega a iniciarse (código de salida 78) en lugar de fallar más tarde en algún punto confuso. Instale la versión LTS actual desde nodejs.org —winget install OpenJS.NodeJS.LTS en Windows, brew install node@24 en macOS—, confirme que node --version muestre v24 o superior e instale Zinnector® nuevamente.
"gyp ERR!", "Building from source with node-gyp" o "You need to install Visual Studio"
El entorno de ejecución de WordPress tiene un módulo nativo cuyos binarios precompilados existen únicamente para Node 24 y 25. En una versión más nueva de Node (26 en adelante, a partir de septiembre de 2026), su instalador recurre a la compilación desde el código fuente, lo que en una máquina con Windows limpio termina en una solicitud de Visual Studio. Solucionado en 0.1.2: Zinnector® detecta esto antes de descargar nada y obtiene un Node 24 solo para el entorno de ejecución (unos 30 MB, verificado con las sumas de comprobación de nodejs.org), por lo que nunca se compila nada. Si aún lo ve después de actualizar, ejecute zinnector dev --reset-runtime para que la instalación a medias anterior se descarte primero.
Advertencias "EPERM" de npm mientras limpia (Windows)
Casi siempre se debe a un antivirus o a un indexador de búsquedas que mantiene un archivo abierto bajo node_modules del entorno de ejecución mientras npm intenta eliminarlo. La instalación se reintenta desde un directorio limpio en el siguiente zinnector dev; si sigue ocurriendo, zinnector dev --reset-runtime elimina primero todo el directorio del entorno de ejecución e instala de nuevo.
"the local playground runtime could not be installed"
El mensaje incluye las últimas líneas del propio npm y el comando exacto que ejecutó Zinnector®, para que pueda ejecutarlo usted mismo y ver la salida completa. Las causas habituales son un problema de red o de proxy —el entorno de ejecución se obtiene con su propio npm, por lo que se aplican npm config set proxy … y un espejo de registro— o una instalación anterior a medio terminar, que --reset-runtime borra.
"the local playground exited before it was ready" o nunca llega a estar listo
Ejecute zinnector dev --verbose para ver la salida propia del entorno de ejecución. Un puerto ya en uso es la causa común: zinnector dev --port 9401, o establezca port en zinnector.json. Un entorno de ejecución que se instaló pero no arranca: zinnector dev --reset-runtime. El primer arranque también descarga WordPress, así que en una conexión lenta dele unos minutos; la CLI espera hasta cinco antes de informar de un tiempo de espera agotado en lugar de quedarse colgada.
"this project is not a git repository" al enviar cambios
Los despliegues se gestionan desde un repositorio, por lo que zinnector push necesita uno con un repositorio remoto al que la plataforma pueda acceder. git init && git add -A && git commit -m initial, añada su remoto de GitHub o GitLab y luego zinnector link para conectarlo al sitio.
El sitio se ve en blanco después de un despliegue
Ejecute zinnector check. Nueve de cada diez veces se trata de una discrepancia en la versión de PHP —compiló en una versión de PHP más reciente que la que ejecuta el espacio— y el informe indica a qué versión cambiar el espacio con zinnector php <version>, o contra cuál desarrollar con zinnector dev --php <version>. zinnector logs --error muestra el error fatal en sí.
Relacionado
¿Sigues con dudas?
El soporte técnico está incluido en todos los planes y respondemos en tu propio idioma.
Contactar con soporte → Todos los artículos →