عیب‌یابی Zinnector®

خطاهایی که کاربران در عمل با CLI مربوط به Zinnector® با آن‌ها مواجه می‌شوند، معنای هر یک و راه‌حل آن. هر ورودی دقیقاً متنی را که مشاهده خواهید کرد نام می‌برد تا بتوانید این صفحه را برای آن جستجو کنید. اگر مورد شما در اینجا نیست، دستور دارای خطا را با ZINNECTOR_DEBUG=1 اجرا کرده و یک مسئله (issue) در github.com/Zinn-Digital/zinnector/issues به همراه خروجی، نسخه node --version و سیستم‌عامل خود ثبت کنید.

خطای "spawn EINVAL" بلافاصله پس از پذیرش نصب زمان‌اجرا (Windows)

یک باگ در Zinnector® نسخه‌های 0.1.0 و 0.1.1. در ویندوز، نصب‌کننده زمان‌اجرا دستور npm.cmd را با نام اجرا می‌کرد، و Node از زمان اعمال اصلاحیه مربوط به CVE-2024-27980 از اجرای یک فایل .cmd بدون shell امتناع کرده است — بنابراین فرآیند نصب یک ثانیه پس از پاسخ Y شما متوقف شد. برطرف‌شده در نسخه 0.1.2: npm اکنون به عنوان node npm-cli.js اجرا می‌شود که در همه پلتفرم‌ها یکسان است و نیازی به shell ندارد. دستور 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، در مک‌اواس brew install node@24 — تأیید کنید که 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)، نصب‌کننده آن به کامپایل کردن از منبع بازمی‌گردد که در یک ماشین ویندوزی معمولی به درخواست برای Visual Studio ختم می‌شود. برطرف‌شده در نسخه 0.1.2: Zinnector® این مورد را قبل از دانلود هر چیزی تشخیص می‌دهد و یک نسخه 24 از Node را به صورت اختصاصی برای زمان‌اجرا دریافت می‌کند — حدود 30 مگابایت، که با چک‌سام‌های nodejs.org مطابقت داده شده است — بنابراین هیچ‌گاه چیزی کامپایل نمی‌شود. اگر پس از ارتقا همچنان آن را مشاهده کردید، zinnector dev --reset-runtime را اجرا کنید تا نصب نیمه‌کاره قبلی ابتدا حذف شود.

هشدارهای "EPERM" از طرف npm در حین پاکسازی (Windows)

تقریباً همیشه یک نرم‌افزار ضد ویروس یا نمایه‌ساز جستجو (search indexer) است که یک فایل را تحت پوشش node_modules زمان‌اجرا باز نگه داشته است در حالی که npm سعی در حذف آن دارد. نصب در دستور بعدی zinnector dev از یک پوشه تمیز مجدداً تلاش می‌شود؛ اگر این اتفاق ادامه داشت، دستور zinnector dev --reset-runtime کل پوشه زمان‌اجرا را ابتدا حذف کرده و دوباره نصب می‌کند.

خطای "the local playground runtime could not be installed"

این پیام شامل آخرین خطوط خودِ npm و دستور دقیقی است که Zinnector® اجرا کرده است، بنابراین می‌توانید آن را خودتان اجرا کرده و خروجی کامل را ببینید. دلایل معمول عبارتند از مشکل شبکه یا پروکسی — زمان‌اجرا با استفاده از npm خود شما دریافت می‌شود، بنابراین npm config set proxy … و یک آینه‌ی رجیستری (registry mirror) اعمال می‌شوند — یا یک نصب قبلی نیمه‌کاره، که --reset-runtime آن را پاک می‌کند.

خطای "the local playground exited before it was ready" یا عدم آمادگی همیشگی آن

دستور zinnector dev --verbose را برای مشاهده خروجی خودِ زمان‌اجرا اجرا کنید. یک پورت که از قبل در حال استفاده است از موارد رایج است: zinnector dev --port 9401، یا port را در zinnector.json تنظیم کنید. زمان‌اجرایی که نصب شده اما بوت نمی‌شود: zinnector dev --reset-runtime. اولین بوت همچنین خودِ WordPress را دانلود می‌کند، بنابراین در یک اتصال کند چند دقیقه به آن زمان بدهید؛ CLI پیش از اعلام زمان‌پایان (timeout) تا پنج دقیقه صبر می‌کند تا اینکه قطع شود.

خطای "this project is not a git repository" هنگام push

استقرارها از یک مخزن هدایت می‌شوند، بنابراین zinnector push به مخزنی نیاز دارد که دارای یک ریموت (remote) باشد که پلتفرم بتواند به آن دسترسی داشته باشد. دستورات git init && git add -A && git commit -m initial را اجرا کنید، ریموت GitHub یا GitLab خود را اضافه کنید، و سپس برای اتصال آن به سایت، zinnector link را اجرا کنید.

سفید بودن سایت پس از استقرار

دستور zinnector check را اجرا کنید. در ۹ مورد از ۱۰ مورد، این یک شکاف نسخه PHP است — شما روی نسخه‌ای جدیدتر از PHP نسبت به اسلات اجرایی ساخته‌اید — و گزارش مشخص می‌کند که با دستور zinnector php <version> نسخه اسلات را به چه چیزی تغییر دهید، یا با دستور zinnector dev --php <version> توسعه را روی کدام نسخه انجام دهید. دستور zinnector logs --error خطای مهلک (fatal) را نشان می‌دهد.

مرتبط

• شروع به کار · توسعه محلی · استقرار · مرجع دستورات