كيفية إصلاح خطأ java.lang.UnsupportedClassVersionError: دليل شامل

مقدمة: "آلة الزمن" لكود جافا الخاص بك

تخيل: قمت بتحميل مكتبة رائعة، وكتبت بضعة أسطر من الكود، ثم ضغطت على "Run" — وبدلاً من برنامج يعمل، ترى رسالة طويلة ومخيفة:

Exception in thread "main" java.lang.UnsupportedClassVersionError: \ncom/example/MyApp has been compiled by a more recent version of the Java Runtime \n(class file version 61.0), this version of the Java Runtime only recognizes \nclass file versions up to 55.0

مألوفة؟ إذا سبق لك أن واجهت java.lang.UnsupportedClassVersionError، فأنت تعلم أن الأمر يشبه محادثة بين شخصين يتحدثان لغتين مختلفتين. برنامجك بلغة Java يتحدث بالإصدار 61.0 (Java 17)، بينما بيئة التشغيل تفهم فقط حتى الإصدار 55.0 (Java 11).

في هذا الدليل، سنشرح ما هو Unsupported major.minor version، ولماذا يحدث، والأهم من ذلك، كيفية إصلاحه. لن نقدم لك حلولاً جاهزة فحسب، بل سنعلمك فهم جذر المشكلة. هيا بنا!

ما هو major.minor version؟ شرح مبسط

كل ملف .class في Java يحتوي على علامة داخلية — major.minor version. هذا هو رقم إصدار تنسيق البايت كود الذي يتم إنشاؤه بواسطة المترجم javac. على سبيل المثال:

\n
• major 52 ← Java 8
\n
• major 55 ← Java 11
\n
• major 61 ← Java 17
\n
• major 65 ← Java 21
\n

عند تشغيل التطبيق، تتحقق JRE (بيئة تشغيل Java) مما إذا كانت تستطيع "فهم" هذا الملف. إذا كان إصدار الملف أحدث من إصدار JRE، فستحصل على java.lang.UnsupportedClassVersionError.

تشبيه بسيط: تخيل أنك تحاول فتح مستند PDF تم إنشاؤه في Adobe Acrobat 2023 باستخدام Adobe Reader 2010. سيخبرك البرنامج: "أنا لا أعرف هذا التنسيق".

الأسباب الرئيسية لخطأ UnsupportedClassVersionError

يمكن أن يحدث خطأ Unsupported major.minor version لعدة أسباب:

\n
• اختلاف إصدارات JDK و JRE: قمت بترجمة الكود على JDK 17، ولكنك تشغله على JRE 11.
\n
• مكتبات الطرف الثالث: أضفت ملف JAR تمت ترجمته تحت Java 17، بينما بيئة التشغيل لديك هي Java 8.
\n
• إعدادات Maven/Gradle غير صحيحة: ملف البناء يحدد إصدار Java معين، بينما الخادم مثبت عليه إصدار آخر.
\n
• النشر على خادم قديم: تقوم بالتطوير على IDE حديث، بينما خادم الإنتاج يعمل على Java قديمة.
\n

دليل خطوة بخطوة: كيفية إصلاح الخطأ

دعنا نستعرض خطوات محددة لحل المشكلة. سننظر في ثلاثة سيناريوهات رئيسية.

الخطوة 1: التحقق من إصدارات Java

أولاً، يجب معرفة من "المخطئ". افتح الطرفية (Terminal) ونفذ الأوامر التالية:

# الإصدار الذي تترجم به (JDK)\njavac -version\n\n# الإصدار الذي تشغل به (JRE)\njava -version

إذا كانا غير متطابقين — فهذا هو السبب. على سبيل المثال، javac يظهر "17.0.1"، بينما java يظهر "11.0.12".

الحل: قم بتثبيت إصدارات متطابقة، إما بتحديث JRE أو بتخفيض إصدار الترجمة (كما هو موضح أدناه).

الخطوة 2: ضبط إعدادات الترجمة

إذا لم تتمكن من تحديث JRE (على سبيل المثال، على الخادم)، فستحتاج إلى ترجمة الكود لإصدار أقدم. استخدم العلامات -source و -target في المترجم:

// ترجمة كود Java 17، ولكن إنشاء بايت كود لـ Java 11\njavac -source 17 -target 11 MyApp.java

ملاحظة مهمة: -source يحدد بناء جمل Java الذي تستخدمه، بينما -target يحدد إصدار JRE الذي سيتم إنشاء ملف .class له. إذا كان كودك يستخدم ميزات Java 17 (مثل تعبيرات switch)، فسيتم ترجمتها إلى بايت كود متوافق.