Tương thích phiên bản plugin và API
Vì sao plugin không chạy trên phiên bản của bạn, api-version nghĩa là gì, cách đọc yêu cầu, và không khớp có thể gây ra gì.
Cập nhật 13 tháng 8, 2026
Plugin được xây dựng cho một phiên bản cụ thể của API máy chủ. Sự không khớp hoặc khiến plugin không tải được, hoặc gây lỗi trong quá trình hoạt động.
Điều gì quyết định khả năng tương thích
- Phiên bản game. Plugin cho 1.20 thường sẽ không hoạt động trên 1.21: các lớp nội bộ thay đổi.
- Core. Bukkit/Spigot/Paper tương thích theo kiểu “từ dưới lên”: plugin Bukkit sẽ chạy trên Paper, nhưng không ngược lại nếu dùng các API riêng của Paper.
- Phụ thuộc. Vault, PlaceholderAPI, ProtocolLib — phiên bản của chúng cũng phải khớp.
api-version
Trong plugin.yml của plugin có ghi:
api-version: 1.21
Nếu hoàn toàn thiếu dòng này, máy chủ coi plugin là legacy và bật chế độ tương thích — trong log sẽ xuất hiện cảnh báo. Đây không phải lỗi, mà là dấu hiệu của một plugin cũ.
Triệu chứng điển hình
| Trong log | Ý nghĩa |
|---|---|
Unsupported API version | Plugin được xây dựng cho core mới hơn |
NoSuchMethodError | Phương thức không còn tồn tại trong phiên bản của bạn — phân tích chi tiết |
NoClassDefFoundError | Thiếu phụ thuộc — phân tích chi tiết |
Invalid plugin.yml | Tệp bị hỏng hoặc đây không phải là plugin — phân tích chi tiết |
Kiểm tra trước khi cài đặt
Danh mục “Plugins và mods” trong bảng điều khiển lọc theo core và phiên bản của bạn, đồng thời cảnh báo về sự không tương thích trước khi cài đặt — Cách cài đặt. Khi tải lên thủ công, hãy kiểm tra trang của plugin: trang luôn liệt kê phạm vi các phiên bản được hỗ trợ.
