플러그인과 API 버전 호환성

내 버전에서 플러그인이 작동하지 않는 이유, api-version이 의미하는 것, 요구 사항을 읽는 방법, 불일치가 일으킬 수 있는 문제를 알아봐요.

업데이트 2026년 8월 13일

플러그인은 특정 서버 API 버전에 맞춰 제작돼요. 버전이 맞지 않으면 플러그인이 로드되지 않거나 작동 중 오류가 발생해요.

호환성을 결정하는 요소

게임 버전. 1.20용 플러그인은 보통 1.21에서 작동하지 않아요. 내부 클래스가 바뀌기 때문이에요.
코어. Bukkit/Spigot/Paper는 “아래에서 위로” 호환돼요. Bukkit 플러그인은 Paper에서 실행되지만, Paper 전용 API를 사용했다면 그 반대는 성립하지 않아요.
의존성. Vault, PlaceholderAPI, ProtocolLib도 버전이 일치해야 해요.

플러그인의 plugin.yml에 다음과 같이 지정돼요.

api-version: 1.21

이 줄이 아예 없으면 서버는 해당 플러그인을 레거시로 간주하고 호환 모드를 활성화해요. 이때 로그에 경고가 나타나요. 이는 오류가 아니라 오래된 플러그인이라는 신호예요.

제어판의 “플러그인과 모드” 카탈로그는 사용 중인 코어와 버전에 따라 필터링하며, 설치 전에 호환성 문제를 경고해요 — 설치 방법. 직접 업로드할 때는 플러그인 페이지를 확인하세요. 지원하는 버전 범위가 항상 표시돼 있어요.

Minecraft 호스팅오프라인일 때도 서버가 실행돼요서버 만들기