انتقل إلى المحتوى الرئيسي

TP1.2 — تثبيت Maven 3.9.x

الأهداف​

هذا العمل العملي سيمكنك من:

  • تثبيت Apache Maven 3.9.x على نظام التشغيل الخاص بك
  • تكوين المتغيرات البيئية اللازمة
  • التحقق من أن التثبيت يعمل بشكل صحيح
  • فهم دور Maven في مشروع Spring Boot

المدة المقدرة: 30-45 دقيقة

لماذا Maven؟​

Apache Maven هو أداة البناء القياسية لمشاريع Java وSpring Boot. يدير:

  • التبعيات: تنزيل المكتبات اللازمة تلقائيًا
  • البناء: التجميع، الاختبارات، تعبئة التطبيق
  • دورة الحياة: clean → compile → test → package → install → deploy
كود Java الخاص بك  ──►  Maven  ──►  تطبيق جاهز (.jar)
                        │
                        ├── تنزيل التبعيات
                        ├── تجميع الكود
                        ├── تنفيذ الاختبارات
                        └── إنشاء ملف .jar
النسخة الموصى بها

نستخدم Maven 3.9.x لتوافقه الأمثل مع Java 17+ وSpring Boot 3.x.

المتطلبات الأساسية​

قبل تثبيت Maven، يجب أن يكون لديك Java JDK 17 أو أعلى مثبتًا.

التحقق من Java​

java -version

النتيجة المتوقعة (مثال):

openjdk version "17.0.x" 2024-xx-xx
OpenJDK Runtime Environment ...
OpenJDK 64-Bit Server VM ...

إذا لم يكن Java مثبتًا، راجع دليلنا المفصل:

👉 TP: تثبيت Java JDK 17

أو قم بتنزيله مباشرة من:

التثبيت على Windows​

الخطوة 1: تنزيل Maven​

  1. اذهب إلى https://maven.apache.org/download.cgi
  2. قم بتنزيل الملف Binary zip archive: apache-maven-3.9.9-bin.zip
رابط مباشر

apache-maven-3.9.9-bin.zip

إذا لم تعد النسخة 3.9.9 متاحة، خذ آخر نسخة 3.9.x من صفحة التنزيل.

الخطوة 2: استخراج الأرشيف​

  1. أنشئ مجلد C:\Program Files\Maven (أو C:\maven)
  2. استخرج محتوى الـ ZIP في هذا المجلد
  3. يجب أن يكون لديك: C:\Program Files\Maven\apache-maven-3.9.9
C:\Program Files\Maven\
└── apache-maven-3.9.9\
    ├── bin\
    │   ├── mvn.cmd        ← الملف التنفيذي لـ Maven
    │   └── mvnDebug.cmd
    ├── boot\
    ├── conf\
    │   └── settings.xml
    └── lib\

الخطوة 3: تكوين المتغير MAVEN_HOME​

  1. افتح قائمة ابدأ → اكتب "variables d'environnement"
  2. انقر على "Modifier les variables d'environnement système"
  3. انقر على "Variables d'environnement..."
  4. في Variables système، انقر على Nouveau:
    • Nom de la variable: MAVEN_HOME
    • Valeur de la variable: C:\Program Files\Maven\apache-maven-3.9.9
  5. انقر على OK

الخطوة 4: إضافة Maven إلى PATH​

  1. في Variables système، ابحث عن المتغير Path
  2. انقر على Modifier
  3. انقر على Nouveau
  4. أضف: %MAVEN_HOME%\bin
  5. انقر على OK لإغلاق جميع النوافذ

الخطوة 5: التحقق من التثبيت​

أغلق جميع النوافذ الطرفية المفتوحة، ثم افتح نافذة طرفية جديدة (CMD أو PowerShell):

mvn -version

النتيجة المتوقعة:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: C:\Program Files\Maven\apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
Default locale: fr_CA, platform encoding: UTF-8
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
مهم

إذا لم يتم التعرف على mvn بعد تكوين PATH، أعد تشغيل نافذتك الطرفية أو حتى جهاز الكمبيوتر الخاص بك. المتغيرات البيئية لا تُعاد تحميلها في النوافذ الطرفية المفتوحة بالفعل.

بديل Windows: التثبيت باستخدام Chocolatey​

إذا كان لديك Chocolatey مثبتًا، فإن التثبيت يكون أبسط:

choco install maven --version=3.9.9

بديل Windows: التثبيت باستخدام Scoop​

إذا كان لديك Scoop مثبتًا:

scoop install maven

التثبيت على macOS​

الخيار 1: Homebrew (موصى به)​

Homebrew هو مدير الحزم الأكثر شعبية على macOS.

تثبيت Homebrew (إذا لم يكن مثبتًا بالفعل):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

تثبيت Maven:

brew install maven

التحقق:

mvn -version
تلميح

يقوم Homebrew بتثبيت أحدث إصدار ثابت من Maven 3.9.x تلقائيًا ويقوم بتكوين PATH لك.

الخيار 2: التثبيت اليدوي​

الخطوة 1: تنزيل Maven​

cd ~/Downloads
curl -O https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

الخطوة 2: استخراج الأرشيف​

sudo mkdir -p /opt/maven
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/maven

الخطوة 3: تكوين المتغيرات البيئية​

افتح ملف تعريف shell الخاص بك:

لـ zsh (macOS الافتراضي منذ Catalina):

nano ~/.zshrc

لـ bash:

nano ~/.bash_profile

أضف السطور التالية إلى نهاية الملف:

# Apache Maven
export MAVEN_HOME=/opt/maven/apache-maven-3.9.9
export PATH=$MAVEN_HOME/bin:$PATH

احفظ (Ctrl+O, Enter, Ctrl+X)، ثم أعد تحميل الملف الشخصي:

source ~/.zshrc

الخطوة 4: التحقق​

mvn -version

النتيجة المتوقعة:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/maven/apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
...
OS name: "mac os x", ...

الخيار 3: SDKMAN!​

SDKMAN! هو أداة تدير إصدارات Java وMaven وGradle، إلخ.

# تثبيت SDKMAN!
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# تثبيت Maven
sdk install maven 3.9.9

التثبيت على Linux​

الخيار 1: مدير الحزم (Ubuntu/Debian)​

sudo apt update
sudo apt install maven
انتبه إلى النسخة

قد تحتوي المستودعات الرسمية لـ Ubuntu/Debian على نسخة قديمة من Maven. تحقق من النسخة المثبتة:

mvn -version

إذا كانت النسخة أقل من 3.9، ففضل التثبيت اليدوي أدناه.

الخيار 2: التثبيت اليدوي (موصى به)​

الخطوة 1: تنزيل Maven​

cd /tmp
wget https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz

الخطوة 2: استخراج وتثبيت​

sudo mkdir -p /opt/maven
sudo tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/maven

الخطوة 3: تكوين المتغيرات البيئية​

أنشئ ملف تكوين Maven:

sudo nano /etc/profile.d/maven.sh

أضف المحتوى التالي:

#!/bin/bash
export MAVEN_HOME=/opt/maven/apache-maven-3.9.9
export PATH=$MAVEN_HOME/bin:$PATH

اجعل الملف قابلاً للتنفيذ وقم بتحميله:

sudo chmod +x /etc/profile.d/maven.sh
source /etc/profile.d/maven.sh

الخطوة 4: التحقق​

mvn -version

النتيجة المتوقعة:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/maven/apache-maven-3.9.9
Java version: 17.0.x, vendor: Eclipse Adoptium
...
OS name: "linux", ...

الخيار 3: SDKMAN! (يعمل أيضًا على Linux)​

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

sdk install maven 3.9.9

الخيار 4: Fedora / CentOS / RHEL​

sudo dnf install maven

التحقق النهائي (جميع أنظمة التشغيل)​

بعد التثبيت، افتح نافذة طرفية جديدة ونفذ هذه الأوامر:

# التحقق من Java
java -version

# التحقق من Maven
mvn -version

# التحقق من أن JAVA_HOME معرف
echo $JAVA_HOME       # macOS/Linux
echo %JAVA_HOME%      # Windows CMD
$env:JAVA_HOME        # Windows PowerShell

النتيجة المتوقعة​

يجب أن ترى:

  • Java: النسخة 17 أو أعلى
  • Maven: النسخة 3.9.x
  • JAVA_HOME: يشير إلى تثبيت JDK الخاص بك
إذا لم يكن JAVA_HOME معرفًا

يحتاج Maven إلى المتغير JAVA_HOME. إذا لم يكن معرفًا:

Windows: أضف JAVA_HOME في المتغيرات البيئية للنظام، مشيرًا إلى مجلد JDK الخاص بك (مثال: C:\Program Files\Eclipse Adoptium\jdk-17.0.x)

macOS/Linux: أضف في ~/.zshrc أو ~/.bashrc:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # macOS
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 # Linux (قد يختلف المسار)

اختبار Maven: أول بناء​

لتأكيد أن Maven يعمل، لنقم بإنشاء مشروع اختبار:

mvn archetype:generate \
  -DgroupId=com.test \
  -DartifactId=test-maven \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

إذا قام Maven بتنزيل التبعيات وعرض BUILD SUCCESS، فإن التثبيت لديك مكتمل.

cd test-maven
mvn clean package
[INFO] BUILD SUCCESS
[INFO] Total time:  X.XXX s

يمكنك حذف هذا المجلد التجريبي:

cd ..
rm -rf test-maven       # macOS/Linux
rmdir /s /q test-maven   # Windows CMD

ملخص الأوامر حسب نظام التشغيل​

الإجراءWindowsmacOS (Homebrew)Linux (يدوي)
تثبيتتنزيل ZIP + تكوين PATHbrew install mavenwget + استخراج + PATH
تكوين PATHمتغيرات البيئة للنظامتلقائي/etc/profile.d/maven.sh
التحققmvn -versionmvn -versionmvn -version
التحديثإعادة التنزيلbrew upgrade mavenإعادة التنزيل

حل المشاكل​

mvn غير معروف​

السببالحل
PATH غير مكونأضف MAVEN_HOME/bin إلى PATH
النافذة الطرفية غير معاد تحميلهاأغلق وأعد فتح النافذة الطرفية
المسار غير صحيحتحقق من أن مجلد bin لـ Maven موجود في المسار المكون

JAVA_HOME is not defined correctly​

السببالحل
JAVA_HOME غير معرفتعريف المتغير البيئي JAVA_HOME
JAVA_HOME يشير إلى JREالإشارة إلى JDK (ليس JRE)
مسافة في المساراستخدام علامات الاقتباس: "C:\Program Files\Java\jdk-17"

Maven ينزل ببطء​

أول بناء لـ Maven ينزل الكثير من التبعيات في المجلد ~/.m2/repository. هذا طبيعي ولا يحدث إلا مرة واحدة.

قائمة التحقق من التحقق​

قبل الانتقال إلى الوحدة 2، تأكد من أن كل شيء في مكانه:

  • Java 17+ مثبت وjava -version يعمل
  • Maven 3.9.x مثبت وmvn -version يعمل
  • JAVA_HOME معرف بشكل صحيح
  • اختبار mvn archetype:generate عمل
  • Visual Studio Code مثبت مع ملحقات Java

الخطوات التالية​

بيئتك جاهزة! يمكنك الآن الانتقال إلى الوحدة 2:

➡️ الوحدة 2: الخطوات الأولى مع Spring Boot

⬅️ العودة إلى الوحدة 1