آموزش نصب پلاگین روی سرور Spigot و Paper

برای نصب پلاگین روی سرور Spigot و Paper، فایل JAR پلاگین سازگار با نسخه و نرم‌افزار سرور را دانلود کنید. سرور را متوقف کنید، از فایل‌های آن بکاپ بگیرید و فایل پلاگین را در پوشهٔ plugins بگذارید. سرور را دوباره روشن کنید و در کنسول با دستور plugins فعال‌شدن پلاگین را بررسی کنید. مراحل اصلی نصب در هر دو یکسان است؛ تفاوت مهم، پشتیبانی خود پلاگین از نرم‌افزار و نسخهٔ سرور است.

برای دنبال‌کردن این آموزش، باید از قبل سرور ماینکرفت جاوا با Spigot یا Paper راه‌اندازی کرده باشید و به فایل‌ها و کنسول آن دسترسی داشته باشید. روی هاست، این دسترسی‌ها معمولاً از طریق پنل فراهم می‌شوند. اگر هنوز سرور ندارید، از آموزش راه‌اندازی سرور Paper شروع کنید؛ ساختن پوشهٔ plugins در سرور Vanilla، آن را پلاگین‌پذیر نمی‌کند.

۱. فایل سازگار با سرور را دانلود کنید

در کنسول سرور، بدون اسلش، دستور version را بزنید تا نوع و نسخهٔ سرور را ببینید. سپس صفحهٔ انتشار پلاگین را باز کنید و نسخهٔ ماینکرفت، پشتیبانی از Spigot یا Paper، نسخهٔ Java موردنیاز و وابستگی‌ها را بخوانید. جدیدترین فایل الزاماً مناسب سرور قدیمی نیست. نسخهٔ جاوای مورد استفادهٔ سرور را از تنظیمات اجرای پنل یا محیط راه‌اندازی بررسی کنید؛ دستور version جای بررسی جاوا را نمی‌گیرد.

برای پیدا کردن پلاگین، از بخش منابع SpigotMC یا مخزن Hangar شروع کنید و صفحهٔ سازنده را بررسی کنید. حضور یک فایل در مخزن عمومی، تضمین امنیت آن نیست؛ پلاگین کد اجرایی است و به فایل‌های میزبان دسترسی دارد.

• روی Spigot: فایلی بگیرید که سازنده پشتیبانی از Spigot یا Bukkit را برای نسخهٔ سرورتان اعلام کرده باشد.
• روی Paper: پلاگین‌های Bukkit/Spigot سازگار و پلاگین‌های مخصوص Paper قابل استفاده‌اند؛ پشتیبانی از نسخهٔ دقیق را از صفحهٔ همان انتشار بخوانید.
• فایل مخصوص Paper یا Paper-only را برای Spigot نگیرید. مستندات پلاگین‌های Paper تفاوت بارگذار اختصاصی Paper را توضیح می‌دهد.

وابستگی (Dependency) یعنی پلاگین دیگری که این پلاگین به آن نیاز دارد. وابستگی اجباری باید نصب و فعال باشد؛ اگر ندارید، نسخهٔ سازگار آن را هم بگیرید و در مرحلهٔ بعد همراه پلاگین نصب کنید. وابستگی‌های اختیاری برای امکانات تکمیلی‌اند. نام‌هایی مثل Vault یا ProtocolLib را صرفاً چون در آموزش دیگری دیده‌اید نصب نکنید؛ بخش Requirements یا Dependencies صفحهٔ همان پلاگین را بخوانید.

اگر دانلود یک بستهٔ ZIP بود، آن را استخراج کنید و فایل JAR مناسب پلتفرم را بردارید؛ خود JAR را استخراج نکنید. فایل ماد Forge/Fabric و پلاگین مخصوص Velocity/BungeeCord جای پلاگین این سرور نیست.

برای یک نمونهٔ واقعی، WorldEdit فایل‌های جدا برای پلتفرم‌های مختلف دارد؛ در راهنمای نصب رسمی WorldEdit مسیر Bukkit/Spigot/Paper را دنبال کنید، نه Fabric یا NeoForge.

۲. سرور را متوقف کنید و فایل را در plugins بگذارید

در کنسول stop بزنید یا از دکمهٔ توقف پنل استفاده کنید. تا ذخیره‌شدن دنیا و خاموش‌شدن کامل صبر کنید؛ بستن اجباری پنجره یا گزینهٔ Kill جای توقف معمولی نیست.

پیش از تغییر، از کل پوشهٔ سرور یک بکاپ بگیرید و بیرون از پوشهٔ فعال سرور نگه دارید؛ دنیاها، تنظیمات و دادهٔ پلاگین‌ها باید در آن باشند. اگر پنل ابزار بکاپ دارد، کامل‌شدن بکاپ و محدودهٔ فایل‌هایش را بررسی کنید. برای پلاگینی که داده را در پایگاه دادهٔ خارجی ذخیره می‌کند، از آن داده‌ها هم جدا بکاپ بگیرید. راهنمای به‌روزرسانی Paper بر نگهداری دنیا، تنظیمات و فایل‌های پلاگین تأکید دارد.

حالا بر اساس محل سرور، فایل را منتقل کنید:

• سرور روی کامپیوتر خودتان: پوشهٔ کاری همان سرور را باز کنید؛ معمولاً server.properties و پوشهٔ logs هم آنجا هستند. وارد plugins شوید و فایل JAR را کپی کنید.
• سرور روی هاست: در مدیریت فایل (File Manager) پنل، فایل‌های همان سرور را باز کنید. وارد plugins شوید و JAR را آپلود کنید؛ اگر میزبان SFTP دارد، انتقال از آن مسیر هم ممکن است. صبر کنید آپلود کامل شود.

فایل باید مستقیماً داخل plugins باشد. این ساختار نمونه است؛ ExamplePlugin.jar نام یک فایل فرضی است:

server/
├── server.properties
├── logs/
└── plugins/
    └── ExamplePlugin.jar

دیدن تصویر محل فایل در اندازهٔ کامل

مسیر plugins/downloads/ExamplePlugin.jar اشتباه است. فایل را داخل پوشهٔ تنظیمات پلاگین دیگری هم نگذارید. اگر plugins را نمی‌بینید، ابتدا مطمئن شوید سرور واقعاً Spigot یا Paper است و پوشهٔ درست را باز کرده‌اید؛ پس از اجرای اولیه، این پوشه معمولاً ساخته می‌شود.

همین انتقال JAR و راه‌اندازی مجدد در راهنمای رسمی Spigot توضیح داده شده است. برای اولین نصب، یک پلاگین و وابستگی‌های ضروری‌اش را اضافه کنید تا اگر خطایی بود، منشأ آن راحت‌تر پیدا شود.

۳. سرور را روشن کنید و فعال‌شدن پلاگین را بررسی کنید

از همان روش همیشگی یا دکمهٔ Start پنل، سرور را اجرا کنید. وقتی راه‌اندازی تمام شد، در کنسول سرور بنویسید:

plugins

داخل بازی، فرمان /plugins است و ممکن است دسترسی مدیریتی بخواهد؛ برای این بررسی، کنسول مسیر ساده‌تری است. در خروجی معمول، نام سبز یعنی پلاگین فعال است؛ نام قرمز یعنی فعال نیست و باید گزارش راه‌اندازی را بخوانید. اگر نامش اصلاً دیده نمی‌شود، به بخش رفع خطا بروید.

اگر پنل رنگ‌ها را نشان نمی‌دهد، با حساب دارای دسترسی، /plugins را داخل بازی بررسی کنید. گزارش شروع سرور را هم بخوانید؛ دیدن یک خط Enabling به‌تنهایی کافی نیست، چون ممکن است بعد از آن خطا یا غیرفعال‌شدن ثبت شده باشد. آزمون قابلیت در ادامه، بررسی نصب را کامل می‌کند.

نام ثبت‌شدهٔ پلاگین ممکن است با اسم فایل JAR فرق داشته باشد. برای دیدن نسخهٔ یک پلاگین از version و نام ثبت‌شدهٔ آن استفاده کنید؛ مثلاً اگر WorldEdit نصب کرده‌اید، در کنسول version WorldEdit را بزنید. این دستور فقط اطلاعات پلاگین را می‌خواند.

برای نصب یا عوض‌کردن JAR از توقف و اجرای کامل سرور استفاده کنید. دستور عمومی /reload جای آن نیست؛ مرجع فرمان‌های Paper به‌دلیل مشکلات پلاگین‌ها، راه‌اندازی مجدد را توصیه می‌کند.

تنظیمات و دسترسی بازیکن را بررسی کنید

بسیاری از پلاگین‌ها پس از اجرای اول پوشه‌ای داخل plugins می‌سازند و تنظیماتشان را در فایلی مثل config.yml می‌گذارند. نام پوشه و فایل به پلاگین بستگی دارد؛ ساخته‌نشدن یک فایل با این نام، به‌تنهایی نشانهٔ خرابی نیست. راهنمای تنظیمات پلاگین Paper هم استفاده از قالب‌های مختلف را توضیح می‌دهد.

اگر لازم است تنظیمی را عوض کنید، سرور را متوقف کنید، از فایل تنظیمات کپی بگیرید و فقط گزینهٔ موردنظر را طبق راهنمای همان پلاگین ویرایش کنید. در فایل YAML، تورفتگی‌ها را حفظ کنید و به‌جای Tab از فاصله استفاده کنید. فایل را ذخیره و سرور را دوباره اجرا کنید. دستور بازخوانی تنظیمات مخصوص پلاگین را فقط وقتی به کار ببرید که سازنده آن را مستند کرده باشد.

فعال‌بودن پلاگین با اجازهٔ استفاده از آن فرق دارد. اگر بازیکن پیام نداشتن دسترسی می‌گیرد، نام مجوز (Permission) همان فرمان را از مستندات پلاگین بردارید و به گروه مناسب بدهید. برای این کار آموزش مدیریت دسترسی با LuckPerms کمک می‌کند؛ دادن OP یا مجوز * به همه راه‌حل مناسبی نیست.

در پایان، یک قابلیت کم‌خطر پلاگین را مطابق راهنمایش امتحان کنید؛ برای پلاگین‌های تغییر دنیا این کار را در دنیای آزمایشی انجام دهید. قابلیت عمومی را با حساب بازیکن عادی و دسترسی مناسب هم بسنجید. نصب وقتی کامل است که پلاگین فعال باشد و قابلیت موردنظر با دسترسی درست کار کند.

مثلاً اگر WorldEdit نصب کرده‌اید، به حساب آزمایشی مجوز worldedit.selection.pos بدهید و داخل بازی، در یک نقطه بایستید و //pos1 را وارد کنید. طبق مرجع فرمان‌های WorldEdit این فرمان موقعیت فعلی را به‌عنوان نقطهٔ اول انتخاب ثبت می‌کند؛ پیام ثبت نقطه، نشانهٔ اجرای این قابلیت است و خود فرمان بلوکی را تغییر نمی‌دهد. این یک روش آزمون پیشنهادی است؛ برای پلاگین دیگر، فرمان همان پلاگین را انتخاب کنید.

اگر پلاگین کار نکرد، چه چیزی را بررسی کنیم؟

گزارش اجرای سرور یا لاگ (Log) را از logs/latest.log باز کنید و نام پلاگین را نزدیک زمان شروع سرور پیدا کنید. یک پیام کلی مثل Could not load علت نهایی را مشخص نمی‌کند؛ خط‌های بعدی و بخش Caused by، اگر وجود دارد، سرنخ دقیق‌تری می‌دهند.

دیدن نمودار عیب‌یابی در اندازهٔ کامل

نشانه یا پیام	اقدام بعدی
نام پلاگین در فهرست نیست	مسیر مستقیم داخل plugins، پسوند واقعی .jar، کامل‌بودن آپلود و راه‌اندازی مجدد همان سرور را بررسی کنید. نبودن نام، بررسی لاگ را بی‌نیاز نمی‌کند.
خطای UnknownDependencyException یا Unknown/missing dependency	نام وابستگی را از خطا بخوانید؛ نسخهٔ سازگار آن باید نصب و فعال باشد. اگر از قبل هست، خطای خود آن را بررسی کنید.
خطای Invalid plugin.yml	ممکن است فایل متعلق به پلتفرم دیگری یا دانلود ناقص باشد. فایل مناسب را دوباره از سازنده بگیرید؛ افزودن دستی plugin.yml یا عوض‌کردن پسوند، ماد را به پلاگین تبدیل نمی‌کند.
خطای Ambiguous plugin name	دو فایل از یک پلاگین را هم‌زمان نگه نداشته باشید؛ پس از توقف، نسخهٔ اضافی را از پوشهٔ plugins خارج کنید.
خطای Unsupported API version	پلاگین ممکن است API جدیدتری از سرورتان بخواهد. نسخهٔ سازگار پلاگین را بگیرید؛ ارتقای سرور را فقط پس از بکاپ و بررسی بقیهٔ پلاگین‌ها انجام دهید.
خطای UnsupportedClassVersionError	نسخهٔ کلاس جاوا با محیط اجرا سازگار نیست؛ نیاز Java پلاگین را با جاوایی که واقعاً سرور را اجرا می‌کند مقایسه کنید.
پلاگین فعال است ولی فرمان رد می‌شود	املای فرمان، محل اجرای آن، مجوز بازیکن و تنظیمات همان قابلیت را بررسی کنید. نصب دوباره همیشه مشکل دسترسی را حل نمی‌کند.

خطاهای فایل، وابستگی و نام تکراری در راهنمای نصب و عیب‌یابی Paper توضیح داده شده‌اند. محدودیت نسخهٔ API در مرجع مشخصات پلاگین و معنای خطای نسخهٔ کلاس در مستندات Java آمده است.

روی کامپیوتر، دستور java -version را در ترمینال سیستم اجرا کنید، نه کنسول ماینکرفت. اگر فایل راه‌انداز مسیر جداگانه‌ای برای Java دارد، خروجی جاوای پیش‌فرض سیستم کافی نیست؛ همان مسیر اجرایی را بررسی کنید. روی هاست هم نسخهٔ انتخاب‌شده در تنظیمات اجرای سرور مهم است.

اگر ناسازگاری جاوا تأیید شد، نسخه‌ای را انتخاب کنید که هم سرور و هم پلاگین پشتیبانی کنند. روی کامپیوتر آن را نصب و مسیر Java در فایل راه‌انداز را تنظیم کنید؛ روی هاست، نسخهٔ محیط اجرا را از پنل تغییر دهید یا از پشتیبانی بخواهید. اگر نسخهٔ مشترک سازگاری ندارند، انتشار دیگری از پلاگین لازم است.

اگر هنوز مشکل روشن نیست، نسخهٔ سرور، نام و نسخهٔ پلاگین و متن خطای مربوط را برای پشتیبانی سازنده بفرستید. پیش از اشتراک لاگ، رمزها، توکن‌ها و اطلاعات اتصال خصوصی را حذف کنید. برای مشکلات گسترده‌تر، راهنمای رفع مشکلات سرور ماینکرفت را بخوانید.

به‌روزرسانی یا حذف پلاگین بدون ازدست‌دادن تنظیمات

برای به‌روزرسانی، توضیحات نسخهٔ جدید را بخوانید و سازگاری آن را بررسی کنید. سرور را متوقف کنید و از وضعیت فعلی بکاپ بگیرید. JAR قبلی را به محلی بیرون از plugins منتقل کنید و فایل جدید را جای آن بگذارید؛ پوشهٔ داده و تنظیمات را نگه دارید، مگر راهنمای مهاجرت سازنده تغییر مشخصی بخواهد. بعد از اجرا، لاگ و قابلیت‌های موردنیاز را دوباره بررسی کنید.

اگر نسخهٔ جدید ساختار داده را تغییر داده باشد، بازگرداندن JAR قدیمی به‌تنهایی کافی نیست. برای بازگشت، فایل اجرایی و دادهٔ سازگار همان بکاپ را طبق راهنمای پلاگین برگردانید.

برای حذف، سرور را متوقف کنید و JAR را از plugins خارج کنید. پیش از روشن‌کردن، بررسی کنید پلاگین دیگری به آن وابسته نباشد. پوشهٔ داده را تا وقتی از حذف مطمئن نشده‌اید نگه دارید؛ حذف JAR الزاماً تغییرات قبلی پلاگین در دنیا یا پایگاه داده را برنمی‌گرداند.

برای ادامهٔ کار با یک پلاگین مشخص، آموزش نصب و استفاده از WorldEdit را ببینید؛ انتخاب فرمان‌ها و مجوزها باید بر اساس همان پلاگین باشد.