Khắc phục sự cố Zinnector®

Các lỗi mà người dùng thực sự gặp phải với Zinnector® CLI, ý nghĩa của từng lỗi và cách khắc phục. Mỗi mục đều nêu rõ văn bản chính xác mà quý vị sẽ thấy, vì vậy quý vị có thể tìm kiếm trên trang này. Nếu lỗi của quý vị không có ở đây, hãy chạy lệnh bị lỗi với ZINNECTOR_DEBUG=1 và mở một vấn đề tại github.com/Zinn-Digital/zinnector/issues kèm theo phần đầu ra, lệnh node --version và hệ điều hành của quý vị.

"spawn EINVAL" ngay sau khi chấp nhận cài đặt môi trường thời gian chạy (Windows)

Một lỗi trong Zinnector® 0.1.0 và 0.1.1. Trên Windows, trình cài đặt môi trường thời gian chạy đã chạy npm.cmd theo tên, và Node đã từ chối khởi chạy tệp .cmd mà không có shell kể từ bản sửa lỗi cho CVE-2024-27980 — do đó quá trình cài đặt đã gặp sự cố một giây sau khi quý vị trả lời Y. Đã khắc phục trong 0.1.2: npm bây giờ được chạy dưới dạng node npm-cli.js, giống nhau trên mọi nền tảng và không cần shell. Hãy chạy npm install -g zinnector@latest, sau đó chạy lại zinnector dev.

"npm WARN EBADENGINE" trong quá trình cài đặt, hoặc "Zinnector® needs Node 24 or newer"

Phiên bản Node của quý vị cũ hơn phiên bản 24. npm hiển thị cảnh báo vì gói này khai báo engines: >=24.18.1; quá trình cài đặt vẫn hoàn tất, nhưng sau đó zinnector từ chối khởi động (mã thoát 78) thay vì gặp lỗi ở một vị trí khó hiểu nào đó sau này. Hãy cài đặt phiên bản LTS hiện tại từ nodejs.org — winget install OpenJS.NodeJS.LTS trên Windows, brew install node@24 trên macOS — xác nhận rằng node --version hiển thị v24 trở lên, và cài đặt lại Zinnector®.

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

Môi trường thời gian chạy WordPress có một mô-đun gốc có các tệp nhị phân được biên dịch sẵn chỉ dành cho Node 24 và 25. Trên phiên bản Node mới hơn (26 trở lên, tính đến tháng 9 năm 2026), trình cài đặt của nó sẽ quay về việc biên dịch từ mã nguồn, trên một máy Windows thông thường sẽ dẫn đến yêu cầu cài đặt Visual Studio. Đã khắc phục trong 0.1.2: Zinnector® phát hiện điều này trước khi tải xuống bất kỳ thứ gì và lấy phiên bản Node 24 dành riêng cho môi trường thời gian chạy — khoảng 30 MB, được xác minh bằng tổng kiểm tra của nodejs.org — do đó không có gì bị biên dịch bao giờ. Nếu quý vị vẫn nhìn thấy lỗi này sau khi nâng cấp, hãy chạy zinnector dev --reset-runtime để quá trình cài đặt chưa hoàn tất trước đó bị loại bỏ trước.

Cảnh báo "EPERM" từ npm trong quá trình dọn dẹp (Windows)

Hầu như luôn là do phần mềm quét vi-rút hoặc trình lập chỉ mục tìm kiếm đang giữ tệp mở trong thư mục node_modules của môi trường thời gian chạy trong khi npm cố gắng xóa tệp đó. Quá trình cài đặt sẽ được thử lại từ một thư mục sạch trong lần chạy zinnector dev tiếp theo; nếu tình trạng này vẫn tiếp diễn, zinnector dev --reset-runtime sẽ xóa toàn bộ thư mục môi trường thời gian chạy trước và cài đặt lại.

"the local playground runtime could not be installed"

Thông báo bao gồm các dòng cuối cùng của chính npm và lệnh chính xác mà Zinnector® đã chạy, để quý vị có thể tự chạy lệnh đó và xem toàn bộ đầu ra. Nguyên nhân thông thường là sự cố mạng hoặc proxy — môi trường thời gian chạy được lấy bằng chính npm của quý vị, do đó npm config set proxy … và một máy chủ nhân bản kho lưu trữ sẽ được áp dụng — hoặc một quá trình cài đặt dở dang trước đó, mà --reset-runtime sẽ xóa sạch.

"the local playground exited before it was ready", hoặc nó không bao giờ sẵn sàng

Hãy chạy zinnector dev --verbose để xem đầu ra của chính môi trường thời gian chạy. Cổng đang được sử dụng là nguyên nhân phổ biến: zinnector dev --port 9401, hoặc đặt port trong zinnector.json. Môi trường thời gian chạy đã cài đặt nhưng không chịu khởi động: zinnector dev --reset-runtime. Lần khởi động đầu tiên cũng tải xuống chính WordPress, vì vậy trên kết nối chậm, vui lòng đợi vài phút; CLI sẽ đợi tối đa năm phút trước khi báo cáo thời gian chờ thay vì bị treo.

"this project is not a git repository" khi đẩy (push)

Các bản triển khai được thực hiện từ một kho lưu trữ, vì vậy zinnector push cần một kho lưu trữ có kho lưu trữ từ xa mà nền tảng có thể truy cập. git init && git add -A && git commit -m initial, thêm kho lưu trữ từ xa GitHub hoặc GitLab của quý vị, sau đó dùng zinnector link để kết nối nó với trang web.

Trang web hiển thị màu trắng sau khi triển khai

Hãy chạy zinnector check. Mười lần như một, đó là khoảng cách phiên bản PHP — quý vị đã xây dựng trên phiên bản PHP mới hơn phiên bản mà khe chạy — và báo cáo cho biết nên chuyển khe sang phiên bản nào bằng zinnector php <version>, hoặc phát triển dựa trên phiên bản nào bằng zinnector dev --php <version>. zinnector logs --error hiển thị chính lỗi nghiêm trọng.

Liên quan

• Bắt đầu · Phát triển cục bộ · Triển khai · Tài liệu tham khảo lệnh