Почему java -jar игнорирует твой -cp и как это обойти

Привет, Хабр!

Когда java -jar цинично игнорирует ваш -cp, хочется грустить, но спокойствие, сегодня рассмотрим, почему так происходит и как это обойти.

Откуда ноги растут: приоритет Class-Path’а в -jar

JVM при запуске с -jar делает две нетривиальные вещи:

Создаёт Application ClassLoader и кладёт в него: сам запущенный JAR, всё, что перечислено в Class-Path манифеста. Игнорирует всё, что вы пытались подсунуть через -cp или CLASSPATH.

Логика: гарантировать повторяемый запуск одной капсулы кода.

Пример:

# структура проекта src/   com/example/App.java libs/   commons-lang3-3.14.0.jar  # компиляция javac -d out src/com/example/App.java  # манифест без Class-Path echo "Main-Class: com.example.App" > MANIFEST.MF  # сборка jar cfm app.jar MANIFEST.MF -C out .  # «Ложная надежда»: пробуем передать -cp java -cp libs/commons-lang3-3.14.0.jar -jar app.jar # получаем NoClassDefFoundError – зависимость не видна

Что именно должно быть в MANIFEST.MF

Минимальный набор для самостоятельного JAR»а:

Manifest-Version: 1.0 Main-Class: com.example.App Class-Path: libs/commons-lang3-3.14.0.jar libs/guava-33.0.0.jar

Пути относительные к расположению JAR»а. Разделитель — пробел, а не запятая. Переносы — только CRLF или LF + пробел в начале продолжения строки. Максимум 72 байта в строке — придётся разбивать. Если библиотек много — лучше переключаться на uber‑JAR.

Автоматическая генерация в Gradle

jar {     manifest {         attributes(             'Main-Class': 'com.example.App',             'Class-Path': configurations.runtimeClasspath                           .collect { "libs/${it.name}" }                           .join(' ')         )     }     from {         configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }     } }

Не только пишем Class-Path, но и кладём зависимости в libs/ рядом с app.jar.

Собираем JAR с встроенным classpath

Gradle Shadow Plugin

plugins {     id 'com.github.johnrengelman.shadow' version '8.1.1' }  shadowJar {     archiveClassifier.set('')     minimize()        // срежет неиспользуемые классы }

Запускаем:

./gradlew shadowJar java -jar build/libs/app.jar  # работает без внешних lib’ов 

Shadow перезаписывает MANIFEST.MF — Class-Path исчезает. Все классы зависимостей пакуются внутрь. Возможность shade»ить пакеты, чтобы избежать конфликтов версий.

Maven Shade

<plugin>   <groupId>org.apache.maven.plugins</groupId>   <artifactId>maven-shade-plugin</artifactId>   <version>3.5.1</version>   <executions>     <execution>       <phase>package</phase>       <goals><goal>shade</goal></goals>       <configuration>         <transformers>           <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">             <mainClass>com.example.App</mainClass>           </transformer>         </transformers>       </configuration>     </execution>   </executions> </plugin>

Альтернатива № 1: Main-Class + shell-обёртка

Когда хотите держать JAR чистым, а зависимости — в libs/:

Bash-launcher (run.sh)

#!/usr/bin/env bash SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" java \   -cp "$SCRIPT_DIR/libs/*:$SCRIPT_DIR/app.jar" \   com.example.App "$@" 

"$@" прокидывает аргументы дальше. На Windows аналогичный .cmd с set CLASSPATH= и ; вместо :.

Но минус: два артефакта вместо одного.

Альтернатива № 2: Jigsaw + jlink

С Java 9+ можно пойти дальше и вообще отказаться от класса‑паса:

# module-info.java module com.example.app {     requires org.apache.commons.lang3; }  # сборка jlink \   --module-path mods:$(jdeps --print-module-path libs/*.jar | tr ':' '\n') \   --add-modules com.example.app \   --output dist  ./dist/bin/com.example.app

Получаем самодостаточный runtime, лишний код отрезан, класс‑паса нет. Весит столько, сколько нужно приложению, а не целый JDK.

Профилактика NoClassDefFoundError

Мгновенный рентген запущенной JVM

# Показать, какие JAR'ы реально проглотил AppClassLoader jcmd $(pgrep -f app.jar) VM.classloaders | less

Команда (jcmd ... VM.classloaders) доступна с JDK 11+. Видно иерархию лоудеров, от Bootstrap до пользовательских, плюс список JAR»ов.

Летучий аудит: -verbose:class

Временно перезапускаем сервис с дополнительным флагом:

java -jar -verbose:class app.jar | grep "com.google.common.base.Preconditions"

JVM печатает каждую загрузку класса и JAR‑источник. Ловим момент, когда нужный класс ищется, но не находится. Сохраняйте вывод в файл и фильтруйте grep.

jdeps против слепых зон

Когда не уверены, в каком JAR‑файле должен лежать класс:

# покажет транзитивные зависимости jdeps --recursive --multi-release 17 app.jar | less

Флаг --multi-release важен для multi‑release JAR»ов. Если в выводе нет нужного модуля/пакета — значит, его правда забыли уложить в Class-Path или uber‑JAR.

Правильный Docker-слой

Контейнеры часто прячут проблему:

# Анализируем лёгкий runtime, собранный jlink'ом FROM eclipse-temurin:17-jre COPY dist/ /opt/app/  ENTRYPOINT ["/opt/app/bin/com.example.app"]

Если JAR‑ы кладутся в ${APP_HOME}/libs, проверьте, что COPY действительно подтягивает libs/*. Для multi‑stage‑build удобно держать артефакты в /build и копировать ровно то, что надо:

COPY --from=builder /build/app.jar /opt/app/app.jar COPY --from=builder /build/libs /opt/app/li

Когда uber-JAR или jlink — не ваш выбор

Частые обновления и микро‑патчи. Если вы выкатываете сервис десятками мелких версий в день, собирать и тащить 50-мегабайтный uber‑JAR или целый jlink‑runtime ради фикса из пары классов экономически бессмысленно. Инкрементные деплой‑стратегии (JRebel, Spring DevTools, hot‑swap в Kubernetes) теряют прелесть, потому что каждый пуш превращается в полный ребилд > перекладка жирного артефакта.

Динамические плагины и runtime‑скрипты. Приложения, которые по ходу жизни подтягивают сторонние JAR‑ы (DSL‑engine, плагинная архитектура, Apache Beam JobServer), требуют гибкого classpath»а. Uber‑JAR запечатывает вселенную, а jlink строит кастомный JRE без возможности --add-modules на лету. В таких случаях shell‑лаунчер с аккуратным -cp "$LIBS/*:$EXT/*" остаётся единственным адекватным вариантом.

---

Если у вас полтора JAR»а зависимостей — прописывайте их в манифесте. Если десятки — соберите uber‑JAR и спите спокойно. Нужен fine‑grained контроль и дистрибутив ≤ 40 MB? Пора познакомиться с jlink. А когда инфраструктура требует — пишите shell‑лаунчер, добавьте health‑check и резвитесь с JVM флагами.

Если вы сталкивались с неожиданными тормозами Hibernate из-за неправильных JPQL-запросов, рекомендую посетить открытый урок 19 июня — на нём подробно разберете, как избежать типичных ошибок и повысить производительность в несколько раз. Это практический урок с конкретными приёмами оптимизации — от выявления антипаттернов до эффективного использования JOIN FETCH и кэширования.

Если тема интересна — записывайтесь на странице курса «Java Developer. Professional».

Готовы проверить свои знания Java? Пройдите короткое вступительное тестирование и узнайте, насколько уверенно вы разбираетесь в теме.