Bắt đầu với Zinnector®, giao diện dòng lệnh dành cho nhà phát triển

Zinnector® là công cụ dòng lệnh miễn phí, được cấp phép theo giấy phép MIT của Zinn Digital® dành cho các nhà phát triển WordPress. Công cụ này tạo bộ khung cho một trang web, chạy một trang WordPress thực tế trên máy tính của Quý vị mà không cần cài đặt gì ngoài Node — không cần Docker, không cần MAMP, không cần PHP trên đường dẫn (PATH) — sau đó kiểm tra những gì Quý vị đã xây dựng so với khe lưu trữ mà Quý vị chuẩn bị triển khai và đẩy mã lên. Hướng dẫn này sẽ đưa Quý vị từ con số không đến một trang web đang chạy trong khoảng hai phút, đồng thời cho Quý vị biết dấu hiệu thành công ở từng bước để Quý vị biết khi nào có sự cố xảy ra.

Những gì Quý vị cần

• Node 24 trở lên. Chạy lệnh node --version; lệnh này phải in ra v24 trở lên. Cài đặt phiên bản LTS hiện tại từ nodejs.org — trên Windows dùng winget install OpenJS.NodeJS.LTS, trên macOS dùng brew install node@24.
• npm, đi kèm với Node. Zinnector® sử dụng npm một lần để tải xuống môi trường thời gian chạy WordPress vào bộ nhớ đệm của riêng công cụ này.
• git, chỉ dùng cho lệnh zinnector push — việc triển khai được thực hiện từ kho mã (repository) của Quý vị.
• Docker, chỉ khi Quý vị yêu cầu sử dụng tùy chọn --runtime docker. Môi trường thời gian chạy mặc định không cần Docker.

Không có phần nào dưới đây yêu cầu tài khoản. Khóa API chỉ cần thiết khi Quý vị truy cập vào một khe lưu trữ, trong phần Triển khai với Zinnector®.

Bước 1 — cài đặt công cụ

npm install -g zinnector

Nếu npm in ra thông báo npm WARN EBADENGINE, phiên bản Node của Quý vị cũ hơn yêu cầu >=24.18.1 mà gói phần mềm này khai báo. Quá trình cài đặt vẫn hoàn tất, nhưng giao diện dòng lệnh (CLI) sẽ từ chối chạy. Vui lòng nâng cấp Node trước, sau đó tiến hành cài đặt lại.

Bước 2 — kiểm tra phiên bản

zinnector --version

Thành công: hiển thị số phiên bản, ví dụ 0.1.2. Nếu Quý vị thấy thông báo "Zinnector® needs Node 24 or newer — this is Node 20.x" (Zinnector® cần Node 24 trở lên — đây là phiên bản Node 20.x), tệp nhị phân đã được cài đặt nhưng phiên bản Node của Quý vị quá cũ; lệnh này sẽ thoát với mã lỗi 78 thay vì thực hiện bất kỳ hành động nào.

Bước 3 — đọc tài liệu trợ giúp

zinnector --help

Thành công: hiển thị một bảng tên năm lệnh trong quy trình (new, dev, link, check, push) cùng với mục đích của từng lệnh chỉ trong một dòng. Mỗi lệnh cũng hỗ trợ tùy chọn --help của riêng nó — ví dụ zinnector dev --help sẽ liệt kê các cờ (flags) về môi trường thời gian chạy, PHP và cổng kết nối. Danh sách đầy đủ, kèm theo ví dụ, có trong phần tài liệu tham khảo lệnh.

Bước 4 — tạo bộ khung cho trang web

zinnector new my-site

Thành công: hiển thị tiêu đề Created my-site và danh sách các tệp đã được tạo — zinnector.json, cấu trúc thư mục wp-content gồm các thư mục plugins/, themes/ và tệp hỗ trợ mu-plugins/, tệp .gitignore và tệp README — theo sau là các lệnh tiếp theo cần chạy. Không có thành phần nào trong đó là văn bản giữ chỗ; dự án có thể khởi động ngay ở trạng thái hiện tại. Sử dụng --template plugin hoặc --template theme để tạo bộ khung cho một plugin hoặc một giao diện khối (block theme) có thể hoạt động ngay từ thời điểm được tạo ra.

Bước 5 — chạy trang web

cd my-site
zinnector dev

Lần chạy đầu tiên, Zinnector® sẽ hỏi xác nhận một lần trước khi tải xuống môi trường thời gian chạy WordPress — dung lượng khoảng 570 MB, vì bao gồm mọi phiên bản PHP từ 5.2 đến 8.5 — vào thư mục bộ nhớ đệm riêng, tuyệt đối không đưa vào thư mục dự án của Quý vị. Hãy trả lời Y, hoặc truyền tham số --yes để bỏ qua câu hỏi này. Trên phiên bản Node 26 trở lên, công cụ này cũng sẽ tải thêm một phiên bản Node 24 dành riêng cho môi trường thời gian chạy (dung lượng khoảng 30 MB, đã được xác thực với mã tổng kiểm tra (checksum) của nodejs.org), do mô-đun gốc của môi trường thời gian chạy chỉ có sẵn các tệp nhị phân được biên dịch sẵn cho Node 24 và 25; Quý vị không cần phải cài đặt trình biên dịch hay Visual Studio.

Thành công: hiển thị một khối thông tin nêu tên dự án, phiên bản PHP và phiên bản WordPress, sau đó:

✔ running at http://127.0.0.1:9400
  admin: http://127.0.0.1:9400/wp-admin  (already signed in)

Bước 6 — mở trang web

Truy cập địa chỉ http://127.0.0.1:9400 trên trình duyệt. Thành công: một trang WordPress mới có tiêu đề My WordPress Website, được phục vụ bởi phiên bản PHP mà Quý vị đã yêu cầu. Địa chỉ http://127.0.0.1:9400/wp-admin sẽ mở ra trang quản trị (dashboard) trong trạng thái đã được đăng nhập sẵn. Hãy đặt một plugin vào thư mục wp-content/plugins/ hoặc một giao diện vào thư mục wp-content/themes/, nội dung đó sẽ xuất hiện ngay trong lần tải lại trang tiếp theo — môi trường thời gian chạy phục vụ các thư mục đó trực tiếp từ dự án của Quý vị.

Nhấn tổ hợp phím Ctrl-C để dừng lại. Lệnh zinnector dev --once sẽ khởi động môi trường thời gian chạy, in ra các thông tin đang thực sự chạy (phiên bản PHP, phiên bản WordPress, các tiện ích mở rộng đã được tải) rồi dừng lại — tính năng này rất hữu ích khi Quý vị cần bằng chứng xác thực thay vì chỉ là lời hứa.

Các bước tiếp theo

• Phát triển cục bộ với zinnector dev — tìm hiểu về hai môi trường thời gian chạy, cách lựa chọn phiên bản PHP và WordPress, cũng như nội dung nào được phục vụ từ đâu.
• Triển khai với Zinnector® — đăng nhập, liên kết dự án với một khe lưu trữ, chạy kiểm tra trước khi triển khai, và đẩy mã lên.
• Tài liệu tham khảo lệnh — danh sách mọi lệnh, cờ (flag) và ví dụ minh họa.
• Khắc phục sự cố — các lỗi mà người dùng thực tế hay gặp phải và cách khắc phục cho từng lỗi.

Tài liệu tương tự cũng có trong tệp README của gói phần mềm trên npm và trên GitHub, nơi chúng tôi rất hoan nghênh mọi đóng góp qua mục báo cáo sự cố (issues) và yêu cầu kéo (pull requests).