マイクラサーバーのバージョンアップでプラグイン対応を調べる手順。Paperの安定版確認から本番反映まで

マイクラの新しいバージョンが出たけれど、今すぐ上げてよいか迷う
20個以上のプラグインの対応状況を1つずつ調べるのが大変
更新後にワールドが壊れたり動かなくなったりするのが怖い

マイクラの新しいバージョンが公開されると、新要素を早く遊びたい気持ちになる一方で、サーバー全体の更新には慎重さが求められます。

特に多くのプラグインを入れているサーバーでは、1つでも動かなくなるとログインできなくなったり、経済や保護などの主要な機能が止まりかねません。

僕のサーバーでも、新しい26.3が出たタイミングでサーバー本体（Paper）の更新を検討しました。

しかし調査した結果、必須プラグインの未対応や安定版の有無を考慮して、最新の26.3ではなく26.2への更新に留める判断をしました。

この記事で扱う内容は次の4点です。

安定版の有無と必須プラグインの状況から更新先を決める判断基準
APIやGitHubを使ってプラグインの対応状況をまとめて調べる方法
EssentialsXやSpigetで直面しやすい落とし穴と対処法
手元のDocker環境での事前検証から本番サーバーへ反映するまでの手順

自分のサーバーに入っているプラグインの状況を効率よく確かめ、安全にバージョンアップを進められるようになるでしょう。

最新の26.3を見送り26.2への更新を選んだ判断
プラグインの対応状況をAPIやGitHubで効率よく調べる方法
EssentialsXで未対応の警告が出たときの挙動とアイテム辞書の注意点
Spiget APIで特定バージョンを取得する際の注意点
- 特定バージョンを取得するにはproxyエンドポイントを使う
本番適用の前にDockerのローカル環境で検証する手順
本番サーバーへの反映手順と起動後の確認項目
まとめ：マイクラサーバーのバージョンアップは安定版の確認と事前検証で進める

プラグイン	状況
Geyser	正式版はJava 26.2まで。26.3対応はプレビュー版のみで、作者が「本番で使わないで」と明記
Bolt	26.3対応の変更が未マージ
CoreProtect	最新の24.1でも「Minecraft 26.3 is not supported.」と出て起動しない報告あり
Skript	正式版2.16.2は26.2まで。26.3はプレリリース版2.17.0-pre1のみ
EssentialsX	正式版2.22.0は26.1.2まで。26.3対応は開発版のみ

区分	プラグイン
今の版のまま対応	Geyser、Floodgate、Bolt、GriefPrevention、Skript、LuckPerms、VaultUnlocked、Multiverse、PacketEvents、QuickShop-Hikari、WorldEdit、DiscordSRV、ViaVersion、Jobs Reborn、CMILib、BlueMap
更新が必要	CoreProtect（24.0から24.1へ更新）
表記上は未対応	EssentialsX 2.22.0、EssentialsUnlocked 1.0.0.1（どちらも26.1.xまで）

プラグインの対応状況をAPIやGitHubで効率よく調べる方法

サーバーに導入している28個のプラグインを、配布サイトのページで1つずつ確認していく作業には大変な時間がかかります。

そこで各プラットフォームが提供しているAPIやGitHubを活用し、バージョン情報をまとめて確認しました。

Paperのビルドが安定版かどうか確認する

Paper公式のダウンロードAPIであるFill APIを使うと、バージョンごとのビルド情報を一覧で取得できます。

レスポンスに含まれるchannelフィールド（ALPHA、BETA、STABLE）を確認すれば、安定版が出ているかを即座に判別可能です。

STABLEのビルドが1つも存在しなければ、まだ本番サーバーで運用する段階ではないと判断できます。

curl -s https://fill.papermc.io/v3/projects/paper/versions/26.3/builds

Modrinthのプラグイン情報を取得する

Modrinthで配布されているプラグインは、APIを利用して対応バージョンを調べられます。

プロジェクトIDを指定してエンドポイントを呼び出すと、各バージョンが対象とするgame_versions（対応するMinecraftのバージョン一覧）が返ってきます。

curl -s "https://api.modrinth.com/v2/project/<プロジェクトID>/version"

ただし、この対応バージョン情報は作者による自己申告である点に注意してください。

半年前に公開された古いファイルのメタデータに、後から新しいマイクラのバージョン番号を書き足しているケースもあります。

実際に正常動作するかどうかまでは保証されないため、次に挙げるGitHubの情報と併せて確認するのが確実です。

GitHubのIssueやPull Requestで開発状況を調べる

プラグインのGitHubリポジトリで対象のバージョン（26.3など）を検索すると、開発の進捗や不具合の報告といった一次情報が見つかります。

「対応作業を進めている最中」「このバージョンではエラーが出て起動しない」といった開発者のやり取りは、更新判断の大きな材料になるでしょう。

今回の調査でも、CoreProtectが26.3で起動しない不具合や、Geyserの26.3対応が作業段階にあることはGitHubの検索で判明しました。

SpigotMCのプラグイン情報を確認する

SpigotMCでのみ公開されているプラグイン（Jobs RebornやCMILibなど）は、Spiget APIを参照しました。

Spiget APIから取得できるtestedVersions（作者が動作確認を行ったバージョン一覧）と、更新履歴のリリースノートを照らし合わせて対応状況を確認します。

EssentialsXで未対応の警告が出たときの挙動とアイテム辞書の注意点

Paper 26.2でサーバーを起動すると、EssentialsX 2.22.0は起動ログに次のような警告を1回出力します。

[Essentials] You are running an unsupported server version!

この警告が表示される原因は、EssentialsXが対応バージョンの一覧をプラグイン内部のソースコードに直接保持しているためです。

2.22.0は26.2の公開（6月16日）よりも前の5月31日にリリースされた版であるため、一覧の中に26.2が含まれていません。

ただし、これは内部リストとの照合による表示上の警告に過ぎず、経済機能やテレポート機能などは問題なく動作します。

一方で実運用において困るのは、アイテム名の辞書ファイルであるitems.jsonも同様に古い点です。

/giveコマンドなどで26.2から新しく追加されたアイテムを指定すると、未登録の名前として扱われて処理に失敗します。

essentials:itemdb chiseled_bookshelf  → CHISELED_BOOKSHELF（既存のアイテムは認識できる）
essentials:itemdb chiseled_cinnabar   → エラー: 不明なアイテム名

26.2に対応した修正自体は6月16日にGitHub上へ取り込まれていますが、正式なリリース版はまだ公開されていません。

開発版のビルドはGitHub Actionsで自動生成されているものの、ダウンロードにはGitHubアカウントでのログインが必要で、生成から約90日でデータが削除されてしまいます。

そのため僕のサーバーではEssentialsXを2.22.0のまま運用し、新要素のアイテムを配布する際はバニラ標準のminecraft:giveコマンドで代用する運用を取りました。

Spiget APIで特定バージョンを取得する際の注意点

僕のサーバーでは、プラグインのダウンロード元URLを1つの構成ファイルに集約し、バージョン番号を固定して管理しています。

SpigotMCで配布されているプラグインについては、次のようにSpigetのダウンロードURLへバージョン番号のパラメータを付与して指定していました。

https://api.spiget.org/v2/resources/87610/download?version=643295

ところが起動ログを確認したところ、CMILibは指定していた1.5.9.9ではなく、最新版の1.6.0.1がダウンロードされていました。

調査した結果、このURLは末尾の?version=パラメータを無視し、常に最新版のファイルへリダイレクトを返す仕様だったことが分かりました。

HTTP/2 302
location: https://cdn.spiget.org/file/spiget-resources/87610.jar

古いバージョンと新しいバージョンのIDをそれぞれ指定して取得してみても、返ってくるファイルの中身は完全に同一です。

URLにバージョン番号を付与したからといって、正しく版を固定できていると思い込むのは危険と言えるでしょう。

特定バージョンを取得するにはproxyエンドポイントを使う

Spigetには、バージョンごとにファイルをダウンロードするための専用エンドポイントが用意されています。

ダウンロード用URLの形式による挙動の違いは、次の表のとおりです。

URLの形式	挙動
`/resources/<ID>/download?version=<版ID>`	バージョン指定を無視し、常に最新版のファイルへ転送される
`/resources/<ID>/versions/<版ID>/download`	SpigotMCの配布ページへ転送されるだけで、Cloudflareの保護により直接取得できない
`/resources/<ID>/versions/<版ID>/download/proxy`	指定したバージョンのファイルが正しく返ってくる

https://api.spiget.org/v2/resources/87610/versions/643295/download/proxy → CMILib1.5.9.9.jar
https://api.spiget.org/v2/resources/87610/versions/653715/download/proxy → CMILib1.6.0.1.jar

版IDを変更すると、取得されるファイル名やハッシュ値も正しく切り替わることを確認しました。

版IDの数値は、Spiget APIの/resources/<ID>/versionsを呼び出すと取得できます。

ダウンロードURLをproxyエンドポイントへ書き換えてサーバーを起動したところ、ファイルはJobs5.2.6.6.jarのようにバージョン番号が含まれた名前で保存され、古い4216.jarは自動で削除されました。

2回目以降の起動では再ダウンロードが行われず、「already up to date」と判定されます。

ただし、proxyエンドポイントはSpigetのサーバーがSpigotMCからファイルを代理取得して配信する仕組みです。

短い時間に連続してリクエストを送ると「429 Too Many Requests」エラーが返され、取得を拒否されてしまいます。

検証中にサーバーを続けて再起動した際、プラグインの取得失敗によって起動が一度停止し、数秒後の自動再起動で復旧した場面がありました。

検証環境などでサーバーの再起動を頻繁に繰り返す際は、リクエスト制限に注意してください。

本番適用の前にDockerのローカル環境で検証する手順

本番環境へ反映させる前に、手元のDocker環境へ同じプラグイン構成を展開し、Paper 26.2での動作検証を行いました。

1. ワールドデータを退避する

一度26.2で読み込んだワールドデータは、古い26.1.2へ戻すことができません。

不具合が起きた際にロールバックできるよう、作業前に必ずワールドデータを安全な場所へ退避させておきます。

macOS（APFSファイルシステム）を使用している環境であれば、cp -cコマンドを実行すると実データを複製せずにクローンを作成できるため、一瞬でバックアップが完了します。

docker compose stop mc
cp -cR data ../data-26.1.2

2. サーバーを起動してログを確認する

バックアップを退避させたあと、Dockerコンテナをビルドして起動します。

docker compose up -d --build mc
docker logs spa77-smp 2>&1 | grep -E "WARN|ERROR|not supported|Disabling"

コンテナのログから警告やエラー、未対応のメッセージ、プラグインの無効化ログをフィルタリングし、致命的なエラーが発生していないか確認してください。

3. コマンドで主要機能の動作を確認する

サーバー起動後は、RCON（外部からサーバーコマンドを送信する仕組み）を使ってコマンドを実行し、動作確認を行いました。

ワールドデータを書き換えない読み取り系のコマンドを中心に確認した結果は、次の表のとおりです。

コマンド	確認した内容	結果
`plugins`	導入プラグインの一覧	28個すべてが有効化されている
`essentials version`	サーバーバージョンの認識	26.2として認識されている
`vault-info`	経済システムの連携状態	EssentialsXとEssentialsUnlockedが連携している
`balance`、`baltop`	所持金機能の動作	お金の残高やランキング表示が正しく動作する
`mv list`	多重ワールドの読み込み	5つのワールドすべてが正常に読み込まれている
`geyser version`	統合版中継の対応バージョン	「Java: 26.2 - 26.1.2」と表示される

またSkriptに関しては21個のスクリプトがエラーなしで読み込まれ、自作プラグイン8個もすべて正常に起動しました。

本番サーバーへの反映手順と起動後の確認項目

ローカルでの検証を終えたあと、10月2日22時に本番サーバーへ反映させました。

作業自体はおよそ5分程度で完了しています。

本番反映は次の5つのステップで進めました。

1. サーバー停止前の事前告知

サーバー内で遊んでいるプレイヤーがいたため、メンテナンス開始の3分前からゲーム内チャットで停止を案内しました。

2. データの保存とサーバー停止

データの整合性を保つため、コンソールからsave-offとsave-all flushを実行してワールドデータを確実にディスクへ書き出してから、サーバープロセスを停止させます。

3. 完全バックアップの取得

停止状態のサーバーデータを丸ごとアーカイブ化し、バックアップファイルが破損していないかを検証しました（データ容量は約4.9GB）。

4. 新しい設定の取り込み

Gitで管理しているサーバーの構成リポジトリから、更新後のバージョン番号やプラグインのダウンロードURLを取り込みます。

5. 26.2でサーバーを起動

Paper 26.2（build 129）でコンテナを起動し、ヘルスチェックが正常に通るのを待ちました。

起動後の確認項目

起動が完了したあとは、ローカル環境で検証した項目を本番サーバーでも確認します。

本番環境で確かめた内容は次の5点です。

Paper 26.2で起動し、導入している28個のプラグインがすべて有効化されている
管理している5つのワールドがすべて正常に読み込まれている
Jobs 5.2.6.6とCMILib 1.6.0.1が、バージョン番号を含むファイル名で取得されている
Geyserが「Java: 26.2 - 26.1.2、Bedrock: 26.30 - 26.51」に対応している
起動ログに出力されているエラーが、EssentialsXの未対応警告の表示のみにとどまっている

まとめ：マイクラサーバーのバージョンアップは安定版の確認と事前検証で進める

最新バージョンが出たからといって慌てて適用せず、サーバー本体の安定版や主要プラグインの対応状況が整うまで待つのが安全な運用方法です。

バージョンの更新判断に迷ったときは、次の3点を確認してみてください。

PaperのFill APIでSTABLEビルドが提供されているか
サーバーの核となる必須プラグインが正式に対応しているか
表記上は未対応のプラグインでもローカル環境で主要機能が動くか

すべてのプラグインが公式に対応するまで完全に待つ必要はありません。

表記上は未対応でも、手元で主要な機能を動かして確かめれば判断できます。

まずは手元のターミナルでPaperのFill APIを呼び出し、更新を検討しているバージョンのビルド状態を確認してみてください。