Řešení potíží se službou Zinnector®

Chyby, na které uživatelé v rozhraní Zinnector® CLI skutečně narážejí, co každá z nich znamená a jak ji vyřešit. Každá položka uvádí přesný text, který se vám zobrazí, takže jej můžete na této stránce vyhledat. Pokud zde vaše chyba není, spusťte selhávající příkaz s proměnnou ZINNECTOR_DEBUG=1 a otevřete hlášení na github.com/Zinn-Digital/zinnector/issues s výstupem, vaší verzí node --version a vaším operačním systémem.

„spawn EINVAL“ ihned po potvrzení instalace běhového prostředí (Windows)

Chyba ve verzích Zinnector® 0.1.0 a 0.1.1. Na systému Windows spouštěl instalátor běhového prostředí soubor npm.cmd podle názvu a Node od své opravy CVE-2024-27980 odmítá spouštět soubory .cmd bez shellu – instalace proto spadla sekundu poté, co jste odpověděli Y. Opraveno ve verzi 0.1.2: npm se nyní spouští jako node npm-cli.js, což funguje stejně na všech platformách a nevyžaduje shell. Spusťte npm install -g zinnector@latest a poté znovu zinnector dev.

„npm WARN EBADENGINE“ během instalace nebo „Zinnector® needs Node 24 or newer“

Váš Node je starší než verze 24. npm toto varování vypisuje, protože balíček deklaruje engines: >=24.18.1; instalace se přesto dokončí, ale zinnector se následně odmítne spustit (návratový kód 78), aby nedošlo k matoucí chybě později. Nainstalujte aktuální verzi LTS z webu nodejs.org – winget install OpenJS.NodeJS.LTS ve Windows, brew install node@24 v macOS – ověřte, že node --version vypíše v24 nebo vyšší, a nainstalujte Zinnector® znovu.

„gyp ERR!“, „Building from source with node-gyp“ nebo „You need to install Visual Studio“

Běhové prostředí pro WordPress obsahuje nativní modul, jehož předkompilované binární soubory existují pouze pro Node 24 a 25. Na novějším Node (od září 2026 verze 26 a vyšší) se jeho instalátor uchýlí ke kompilaci ze zdrojového kódu, což na čistém počítači se systémem Windows skončí požadavkem na instalaci sady Visual Studio. Opraveno ve verzi 0.1.2: Zinnector® toto detekuje ještě před stažením čehokoli a stáhne Node 24 určený výhradně pro toto běhové prostředí – přibližně 30 MB, ověřeno podle kontrolních součtů z nodejs.org – takže se nikdy nic nekompiluje. Pokud se tato chyba zobrazuje i po aktualizaci, spusťte zinnector dev --reset-runtime, aby se nejprve odstranila nedokončená instalace z dřívějška.

Varování „EPERM“ od npm během čištění (Windows)

Téměř vždy se jedná o antivirový skener nebo indexovací službu vyhledávání, která drží otevřený soubor ve složce node_modules běhového prostředí, zatímco se jej npm pokouší odstranit. Při dalším spuštění zinnector dev se instalace zopakuje z čistého adresáře; pokud potíže přetrvávají, příkaz zinnector dev --reset-runtime nejprve odstraní celý adresář běhového prostředí a provede instalaci znovu.

„the local playground runtime could not be installed“

Zpráva obsahuje poslední řádky samotného npm a přesný příkaz, který Zinnector® spustil, takže jej můžete spustit sami a prohlédnout si úplný výstup. Obvyklou příčinou bývá problém se sítí nebo proxy – běhové prostředí se stahuje pomocí vašeho vlastního npm, takže platí nastavení npm config set proxy … i zrcadla registrů – nebo nedokončená dřívější instalace, kterou vymaže přepínač --reset-runtime.

„the local playground exited before it was ready“ nebo se prostředí nikdy nepřipraví

Spusťte zinnector dev --verbose, abyste viděli vlastní výstup běhového prostředí. Častou příčinou je již obsazený port: použijte zinnector dev --port 9401 nebo nastavte port v souboru zinnector.json. Běhové prostředí, které se nainstalovalo, ale nespustí se: zinnector dev --reset-runtime. První spuštění také stahuje samotný WordPress, proto na pomalejším připojení vyčkejte několik minut; CLI čeká až pět minut, než ohlásí vypršení časového limitu, namísto toho, aby zamrzlo.

„this project is not a git repository“ při nasazení

Nasazení probíhají z repozitáře, takže příkaz zinnector push vyžaduje repozitář se vzdáleným úložištěm (remote), které je pro platformu dostupné. Zadejte git init && git add -A && git commit -m initial, přidejte své vzdálené úložiště pro GitHub nebo GitLab a poté jej pomocí zinnector link propojte s webem.

Web je po nasazení prázdný (bílá obrazovka)

Spusťte zinnector check. V devíti případech z deseti jde o rozdíl ve verzích PHP – projekt jste sestavili na novější verzi PHP, než na které běží daný slot – a výstup hlášení uvádí, na jakou verzi slot přepnout pomocí zinnector php <version>, nebo pro kterou vyvíjet pomocí zinnector dev --php <version>. Příkaz zinnector logs --error zobrazí samotnou fatální chybu.

Související

• Začínáme · Místní vývoj · Nasazení · Přehled příkazů