Dépannage de Zinnector®

Les erreurs que les utilisateurs rencontrent réellement avec la CLI Zinnector et la solution pour chacune d'elles : spawn EINVAL sous Windows, l'avertissement EBADENGINE d'npm, node-gyp demandant Visual Studio sur Node 26, EPERM pendant l'installation, un runtime qui refuse de démarrer et un port déjà utilisé.

Les erreurs que les utilisateurs rencontrent réellement avec la CLI de Zinnector®, leur signification et leur résolution. Chaque entrée indique le texte exact qui s'affiche, afin que vous puissiez faire une recherche sur cette page. Si le vôtre n'y figure pas, exécutez la commande en échec avec ZINNECTOR_DEBUG=1 et signalez un problème sur github.com/Zinn-Digital/zinnector/issues en fournissant la sortie, votre version avec node --version et votre système d'exploitation.

"spawn EINVAL" juste après l'acceptation de l'installation du moteur d'exécution (Windows)

Un bogue dans Zinnector® 0.1.0 et 0.1.1. Sous Windows, le programme d'installation du moteur d'exécution exécutait npm.cmd par son nom, et Node refuse d'exécuter un fichier .cmd sans interpréteur de commandes depuis son correctif pour la vulnérabilité CVE-2024-27980 — l'installation a donc planté une seconde après votre réponse par Y. Corrigé dans la version 0.1.2 : npm s'exécute désormais sous la forme node npm-cli.js, ce qui est identique sur toutes les plateformes et ne nécessite aucun interpréteur de commandes. Exécutez npm install -g zinnector@latest, puis relancez zinnector dev.

"npm WARN EBADENGINE" pendant l'installation, ou "Zinnector® needs Node 24 or newer"

Votre version de Node est antérieure à la version 24. npm affiche cet avertissement car le paquet déclare engines: >=24.18.1 ; l'installation se termine tout de même, mais zinnector refuse ensuite de démarrer (code de sortie 78) plutôt que d'échouer plus tard de manière incompréhensible. Installez la version LTS actuelle depuis nodejs.org — winget install OpenJS.NodeJS.LTS sous Windows, brew install node@24 sous macOS — vérifiez que node --version renvoie v24 ou une version ultérieure, puis réinstallez Zinnector®.

"gyp ERR!", "Building from source with node-gyp", ou "You need to install Visual Studio"

Le moteur d'exécution WordPress possède un module natif dont les binaires précompilés existent uniquement pour Node 24 et 25. Sur une version de Node plus récente (26 et ultérieures, à compter de septembre 2026), son programme d'installation se replie sur une compilation à partir des sources, ce qui, sur une machine Windows standard, se solde par une demande d'installation de Visual Studio. Corrigé dans la version 0.1.2 : Zinnector® détecte cette situation avant de télécharger quoi que ce soit et récupère une version 24 de Node dédiée uniquement au moteur d'exécution — environ 30 Mo, vérifiés par rapport aux sommes de contrôle de nodejs.org — de sorte qu'aucune compilation n'est jamais effectuée. Si le problème persiste après la mise à niveau, exécutez zinnector dev --reset-runtime afin que l'installation incomplète précédente soit d'abord supprimée.

Avertissements "EPERM" de npm lors du nettoyage (Windows)

Il s'agit presque toujours d'un antivirus ou d'un indexeur de recherche qui maintient un fichier ouvert dans le répertoire node_modules du moteur d'exécution pendant que npm tente de le supprimer. L'installation est relancée à partir d'un répertoire propre lors de la prochaine exécution de zinnector dev ; si le problème persiste, zinnector dev --reset-runtime supprime d'abord l'intégralité du répertoire du moteur d'exécution avant de procéder à une nouvelle installation.

"the local playground runtime could not be installed"

Le message inclut les dernières lignes émises par npm ainsi que la commande exacte exécutée par Zinnector®, ce qui vous permet de l'exécuter vous-même et d'en consulter l'intégralité de la sortie. Les causes habituelles sont un problème de réseau ou de proxy — le moteur d'exécution étant récupéré via votre propre instance de npm, les commandes npm config set proxy … et l'utilisation d'un miroir de registre s'appliquent — ou une installation précédente incomplète, que --reset-runtime permet de nettoyer.

"the local playground exited before it was ready", ou l'environnement ne devient jamais prêt

Exécutez zinnector dev --verbose pour afficher la sortie propre au moteur d'exécution. Un port déjà utilisé est la cause la plus fréquente : utilisez zinnector dev --port 9401 ou définissez le paramètre port dans zinnector.json. Si un moteur d'exécution s'est installé mais refuse de démarrer : zinnector dev --reset-runtime. Le premier démarrage télécharge également WordPress lui-même ; par conséquent, en cas de connexion lente, prévoyez quelques minutes. La CLI attend jusqu'à cinq minutes avant de signaler un dépassement de délai (timeout) plutôt que de se bloquer indéfiniment.

"this project is not a git repository" lors d'une publication (push)

Les déploiements étant pilotés depuis un dépôt, zinnector push nécessite un dépôt muni d'un dépôt distant (remote) accessible par la plateforme. Exécutez git init && git add -A && git commit -m initial, ajoutez votre dépôt distant GitHub ou GitLab, puis exécutez zinnector link pour l'associer au site.

Le site est entièrement blanc après un déploiement

Exécutez zinnector check. Neuf fois sur dix, il s'agit d'un décalage de version PHP — vous avez effectué la compilation sur une version de PHP plus récente que celle exécutée par l'emplacement (slot) — et le rapport indique la version vers laquelle basculer l'emplacement à l'aide de zinnector php <version>, ou celle avec laquelle développer via zinnector dev --php <version>. La commande zinnector logs --error affiche l'erreur fatale elle-même.