פתרון בעיות ב-Zinnector®

השגיאות שמשתמשים נתקלים בהן בפועל ב-CLI של Zinnector®, מה המשמעות של כל אחת מהן, וכיצד לתקן אותן. כל פריט מציין את הטקסט המדויק שיוצג לכם, כך שתוכלו לחפש אותו בדף זה. אם השגיאה שלכם אינה מופיעה כאן, הריצו את הפקודה שנכשלה עם ZINNECTOR_DEBUG=1 ופתחו קריאה (issue) בכתובת github.com/Zinn-Digital/zinnector/issues יחד עם הפלט, ה-node --version שלכם ומערכת ההפעלה שלכם.

"spawn EINVAL" מיד לאחר אישור התקנת ה-runtime (Windows)

באג ב-Zinnector® גרסאות 0.1.0 ו-0.1.1. ב-Windows תוכנית ההתקנה של ה-runtime הריצה את npm.cmd לפי שמו, ו-Node מסרבת להפעיל קובץ .cmd ללא מעטפת (shell) מאז התיקון שלה עבור CVE-2024-27980 — ולכן ההתקנה קרסה שניה אחת לאחר שעניתם Y. תוקן בגרסה 0.1.2: npm מופעל כעת כ-node npm-cli.js, אשר זהה בכל הפלטפורמות ואינו דורש מעטפת. הריצו npm install -g zinnector@latest, ולאחר מכן שוב zinnector dev.

"npm WARN EBADENGINE" במהלך ההתקנה, או "Zinnector® needs Node 24 or newer"

גרסת ה-Node שלכם ישנה מ-24. npm מדפיס את האזהרה מכיוון שהחבילה מגדירה engines: >=24.18.1; ההתקנה מסתיימת בכל זאת, אך zinnector מסרב לאחר מכן להתחיל (קוד יציאה 78) במקום להיכשל בשלב מאוחר יותר באופן מבלבל. התקינו את גרסת ה-LTS הנוכחית מ-nodejs.org — באמצעות winget install OpenJS.NodeJS.LTS ב-Windows, או brew install node@24 ב-macOS — ודאו ש-node --version מדפיס v24 ומעלה, והתקינו את Zinnector® שוב.

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

לסביבת הריצה של WordPress יש מודול נייטיב שהקבצים הבינאריים המוכנים מראש שלו קיימים עבור Node 24 ו-25 בלבד. בגרסאות Node חדשות יותר (26 ומעלה, נכון לספטמבר 2026) תוכנית ההתקנה שלו עוברת כברירת מחדל להידור מקוד המקור, מה שמסתיים במחשב Windows רגיל בבקשה להתקין את Visual Studio. תוקן בגרסה 0.1.2: Zinnector® מזהה זאת לפני הורדה של דבר כלשהו ומוריד גרסת Node 24 עבור ה-runtime בלבד — כ-30 MB, מאומת מול סכומי הביקורת של nodejs.org — כך ששום דבר לעולם אינו עובר הידור. אם ההודעה עדיין מופיעה לאחר השדרוג, הריצו zinnector dev --reset-runtime כדי שההתקנה שהופסקה באמצע ממקודם תימחק קודם לכן.

אזהרות "EPERM" מ-npm בזמן שהוא מבצע ניקוי (Windows)

כמעט תמיד מדובר בסורק אנטי-וירוס או במאנדקס חיפוש שמשאיר קובץ פתוח תחת ה-node_modules של ה-runtime בזמן ש-npm מנסה להסיר אותו. ההתקנה תנוסה שוב מתוך ספרייה נקייה בביצוע הבא של zinnector dev; אם זה ממשיך לקרות, הפקודה zinnector dev --reset-runtime מסירה תחילה את כל ספריית ה-runtime ומתקינה מחדש.

"the local playground runtime could not be installed"

ההודעה כוללת את השורות האחרונות של npm עצמו ואת הפקודה המדויקת ש-Zinnector® הריץ, כך שתוכלו להריץ אותה בעצמכם ולראות את הפלט המלא. הסיבות הנפוצות הן בעיית רשת או פרוקסי — ה-runtime מורד באמצעות ה-npm שלכם, ולכן הגדרות npm config set proxy … ושרת מראה של ה-registry חלות — או התקנה קודמת שהופסקה באמצע, אותה מנקה --reset-runtime.

"the local playground exited before it was ready", או שהוא לעולם אינו נהיה מוכן

הריצו zinnector dev --verbose כדי לראות את הפלט של ה-runtime עצמו. יציאה (port) שכבר נמצאת בשימוש היא הסיבה הנפוצה: השתמשו ב-zinnector dev --port 9401, או הגדירו port ב-zinnector.json. עבור runtime שהותקן אך אינו מבצע אתחול: zinnector dev --reset-runtime. האתחול הראשון מוריד גם את WordPress עצמה, לכן בחיבור איטי תנו לזה מספר דקות; ה-CLI ממתין עד חמש דקות לפני שהוא מדווח על תפוגת זמן במקום להיתקע.

"this project is not a git repository" בעת דחיפה (push)

תהליכי פריסה מנוהלים מתוך מאגר, ולכן zinnector push זקוק למאגר עם שרת מרוחק (remote) שהפלטפורמה יכולה לגשת אליו. הריצו git init && git add -A && git commit -m initial, הוסיפו את ה-remote שלכם ב-GitHub או ב-GitLab, ולאחר מכן הריצו zinnector link כדי לקשר אותו לאתר.

האתר מציג מסך לבן לאחר פריסה

הריצו zinnector check. בתשעה מתוך עשרה מקרים מדובר בפער בין גרסאות PHP — בניתם על גרסת PHP חדשה יותר מזו שהסלוט מריץ — והדוח מציין לאיזו גרסה להעביר את הסלוט באמצעות zinnector php <version>, או מול איזו גרסה לפתח באמצעות zinnector dev --php <version>. הפקודה zinnector logs --error מציגה את השגיאה הקריטית (fatal) עצמה.

קשור

• תחילת העבודה · פיתוח מקומי · פריסה · מדריך פקודות