Maven et les JAR locaux : 5 erreurs fatales et leurs solutions

Pourquoi "copier simplement le JAR dans un dossier" ne fonctionne pas ?

Chaque développeur Java qui a déjà été confronté à Maven se heurte tôt ou tard à un mur : "Je dois connecter une ancienne bibliothèque qui n'est pas dans Maven Central. Que faire ?". Vous cherchez sur Google, vous trouvez une question sur Stack Overflow avec des milliers de vues, vous essayez le premier conseil venu — et vous obtenez une ClassNotFoundException ou un Missing artifact.

Ça vous parle ? Dans cet article, nous allons analyser le top des erreurs lors de l'ajout de fichiers JAR locaux dans un projet Maven et, surtout, comment les éviter. Vous apprendrez non seulement la théorie, mais vous verrez aussi du code fonctionnel que vous pourrez immédiatement appliquer dans votre projet Java.

Erreur n°1 : System scope sans systemPath

Le piège le plus courant pour les débutants est d'ajouter une dépendance avec <scope>system</scope>, mais d'oublier de spécifier <systemPath>. Maven essaie honnêtement de trouver le JAR, mais ne sait pas où il se trouve.

À quoi ressemble l'erreur

[ERROR] Failed to execute goal on project my-app: \nCould not resolve dependencies for project com.example:my-app:jar:1.0: \nThe following artifacts could not be resolved: \ncom.example:my-custom-lib:jar:1.0 (absent)

Code incorrect

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <!-- systemPath est absent ! -->\n</dependency>

Solution correcte

Indiquez toujours le chemin complet vers le fichier JAR via <systemPath>. Il est conseillé d'utiliser un chemin relatif à partir de la racine du projet pour ne pas dépendre d'une machine de développement spécifique.

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <systemPath>${project.basedir}/libs/my-custom-lib-1.0.jar</systemPath>\n</dependency>

Important : Le fichier JAR doit se trouver dans le dossier libs/ à l'intérieur de votre projet. Créez-le si ce n'est pas déjà fait.

Erreur n°2 : Oubli de install-file pour les projets multi-modules

Supposons que vous ayez ajouté un JAR local via system scope et que tout fonctionne localement. Mais lorsque vous essayez de compiler le projet sur un serveur CI (Jenkins, GitLab CI) — la construction échoue. Pourquoi ? Parce que le system scope n'est pas transmis de manière transitive et n'entre pas dans le dépôt local de Maven.

Approche correcte : installation du JAR dans le dépôt local

Utilisez la commande mvn install:install-file. Cela ajoutera votre JAR dans ~/.m2/repository, et il sera disponible pour tous les modules du projet et pour les constructions CI.

mvn install:install-file \\\n   -Dfile=libs/my-custom-lib-1.0.jar \\\n   -DgroupId=com.example \\\n   -DartifactId=my-custom-lib \\\n   -Dversion=1.0 \\\n   -Dpackaging=jar \\\n   -DgeneratePom=true

Après cela, dans le pom.xml, vous pouvez spécifier une dépendance normale sans systemPath :

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n</dependency>

Erreur n°3 : Utilisation d'une URL file:// dans les dépôts

Certains développeurs essaient de "tromper" Maven en ajoutant un dossier local comme dépôt via <repository> avec une URL file://. Techniquement, cela fonctionne, mais cela crée une multitude de problèmes :

\n
• Non-portabilité : le chemin /home/user/project/libs ne fonctionnera pas sur une autre machine.
\n
• Confusion avec les versions :