Base di conoscenza
Risoluzione dei problemi di Zinnector®
Gli errori in cui ci si imbatte realmente con la CLI di Zinnector e le relative soluzioni: spawn EINVAL su Windows, l'avviso EBADENGINE di npm, node-gyp che richiede Visual Studio su Node 26, EPERM durante l'installazione, un runtime che non si avvia e una porta in uso.
Gli errori che le persone incontrano effettivamente con la CLI di Zinnector®, il significato di ognuno e la soluzione. Ogni voce riporta il testo esatto che vedrete, così potete cercarlo in questa pagina. Se il vostro non è qui, eseguite il comando fallito con ZINNECTOR_DEBUG=1 e aprite una segnalazione su github.com/Zinn-Digital/zinnector/issues includendo l'output, il vostro node --version e il vostro sistema operativo.
"spawn EINVAL" subito dopo aver accettato l'installazione del runtime (Windows)
Un bug in Zinnector® 0.1.0 e 0.1.1. Su Windows il programma di installazione del runtime eseguiva npm.cmd per nome, e Node rifiuta di avviare un file .cmd senza una shell a partire dalla correzione per la CVE-2024-27980, perciò l'installazione si è interrotta un secondo dopo aver risposto Y. Risolto in 0.1.2: ora npm viene eseguito come node npm-cli.js, che è identico su ogni piattaforma e non richiede alcuna shell. Eseguite npm install -g zinnector@latest, quindi di nuovo zinnector dev.
"npm WARN EBADENGINE" durante l'installazione o "Zinnector® needs Node 24 or newer"
La vostra versione di Node è precedente alla 24. npm stampa l'avviso perché il pacchetto dichiara engines: >=24.18.1; l'installazione viene completata comunque, ma successivamente zinnector si rifiuta di avviarsi (codice di uscita 78) anziché fallire più avanti con un errore poco chiaro. Installate l'attuale versione LTS da nodejs.org — winget install OpenJS.NodeJS.LTS su Windows, brew install node@24 su macOS — verificate che node --version stampi v24 o superiore e installate nuovamente Zinnector®.
"gyp ERR!", "Building from source with node-gyp" oppure "You need to install Visual Studio"
Il runtime di WordPress include un modulo nativo i cui binari precompilati esistono solo per Node 24 e 25. Su una versione di Node più recente (la 26 e successive, a partire da settembre 2026), il programma di installazione passa alla compilazione da codice sorgente, che su un normale computer Windows termina con la richiesta di Visual Studio. Risolto in 0.1.2: Zinnector® lo rileva prima di scaricare qualsiasi elemento e preleva una versione di Node 24 esclusivamente per il runtime — circa 30 MB, verificati tramite i checksum di nodejs.org — in modo che non venga mai compilato nulla. Se continuate a visualizzarlo dopo l'aggiornamento, eseguite zinnector dev --reset-runtime in modo che l'installazione parziale precedente venga eliminata per prima.
Avvisi "EPERM" da parte di npm durante la pulizia (Windows)
Quasi sempre si tratta di un software antivirus o di un servizio di indicizzazione della ricerca che tiene aperto un file all'interno della cartella node_modules del runtime mentre npm tenta di rimuoverlo. L'installazione viene ripetuta da una directory pulita al successivo comando zinnector dev; se il problema persiste, zinnector dev --reset-runtime rimuove prima l'intera directory del runtime ed esegue nuovamente l'installazione.
"the local playground runtime could not be installed"
Il messaggio include le ultime righe prodotte da npm e il comando esatto eseguito da Zinnector®, così potete eseguirlo autonomamente e visualizzare l'output completo. Le cause più comuni sono un problema di rete o di proxy — il runtime viene scaricato tramite il vostro npm, quindi trovano applicazione le impostazioni npm config set proxy … e un mirror del registry — oppure un'installazione precedente incompleta, che --reset-runtime provvede a ripulire.
"the local playground exited before it was ready" oppure non diventa mai pronto
Eseguite zinnector dev --verbose per visualizzare l'output del runtime. Una porta già in uso è la causa più comune: zinnector dev --port 9401, oppure impostate port all'interno di zinnector.json. Per un runtime installato ma che non si avvia: zinnector dev --reset-runtime. Il primo avvio scarica anche WordPress stesso, quindi su una connessione lenta concedetevi qualche minuto; la CLI attende fino a cinque minuti prima di segnalare un timeout anziché bloccarsi.
"this project is not a git repository" al momento del push
I rilasci vengono gestiti a partire da un repository, quindi zinnector push ne richiede uno dotato di un remote raggiungibile dalla piattaforma. git init && git add -A && git commit -m initial, aggiungete il vostro remote GitHub o GitLab e infine eseguite zinnector link per collegarlo al sito.
Il sito appare completamente bianco dopo un rilascio
Eseguite zinnector check. Nove volte su dieci si tratta di una differenza nella versione di PHP: avete eseguito la compilazione su una versione di PHP più recente rispetto a quella in esecuzione nello slot, e il report indica la versione a cui passare lo slot tramite zinnector php <version>, oppure quella su cui sviluppare tramite zinnector dev --php <version>. zinnector logs --error mostra direttamente l'errore fatale.
Correlati
Ancora bloccato?
Il supporto è incluso in ogni piano con risposte nella tua lingua.
Contatta il supporto → Tutti gli articoli →