Команды Maven: шпаргалка mvn с примерами и частые ошибки

Перед коммитом разработчик по привычке запускает mvn clean install -DskipTests и видит BUILD SUCCESS. Проверки, ради которой команду запускали, не было: тесты пропущены, зато в ~/.m2/repository установлен jar с непроверенным кодом, и проект, зависящий от этой SNAPSHOT-версии, подхватит его при следующей сборке. Для проверки перед коммитом нужна mvn verify, а clean — не каждый раз, а когда в target могли остаться следы удалённых классов.

Команда mvn — это запуск Maven из командной строки в формате mvn [ключи] [фазы и цели]. Фаза (compile, package, verify) выполняет жизненный цикл до себя включительно, цель плагина в форме префикс:цель (dependency:tree) — одно действие плагина без предыдущих шагов, а ключи (-U, -o, -pl, -D) меняют режим работы. Ниже — шпаргалка (cheat sheet) по командам всего модуля со ссылками на подробные уроки и таблица частых ошибок. Примеры рассчитаны на Maven 3.9.x.

Синтаксис mvn: фазы, цели и ключи

Команда Maven состоит из ключей и списка фаз и целей, которые выполняются слева направо. Фаза запускает все предыдущие фазы своего жизненного цикла, цель — только саму себя. Цель записывают через префикс плагина (dependency:tree) или полными координатами groupId:artifactId[:version]:goal.

Короткие префиксы Maven по умолчанию ищет в группах org.apache.maven.plugins и org.codehaus.mojo, поэтому работают exec:java и versions:... без объявления в pom.xml. Если сборка упала, mvn завершается с ненулевым кодом выхода — на этом построены CI-скрипты. Разница фазы и цели с примером пустого jar — в разделе Фаза и цель (goal), формы вызова плагина — в разделе Плагин и цель.

Сборка: clean, package, verify, install

Для ежедневной сборки хватает фаз compile, test, package и verify: последняя прогоняет все тесты и проверки и оставляет артефакт в target. install нужен, только когда артефакт должен увидеть другой проект на этой машине, deploy — для публикации в удалённый репозиторий.

Многомодульному проекту install для связи модулей не нужен: внутри одной сборки reactor передаёт модулям результаты соседей напрямую (Агрегация и reactor).

Тесты: пропуск и запуск отдельных тестов

Чтобы пропустить тесты, используют -DskipTests: тестовый код компилируется, но не запускается. -Dmaven.test.skip=true не компилирует тесты вовсе и нужен редко. Отдельный класс или метод запускают параметром Surefire -Dtest, интеграционный тест — параметром failsafe -Dit.test.

Запуск приложения

Maven собирает приложение, но запускать его удобнее обычной командой java. Для быстрого запуска из исходников подходит цель exec:java плагина exec-maven-plugin (MojoHaus, org.codehaus.mojo): она выполняет метод main внутри JVM самого Maven с classpath проекта.

Зависимости и обновления версий

Команды для зависимостей дают два плагина: maven-dependency-plugin (дерево, анализ, загрузка, очистка локального репозитория) и versions-maven-plugin от MojoHaus (поиск новых версий библиотек и плагинов). Ни одна из этих целей не меняет pom.xml, кроме versions:set и других целей versions, которые явно правят версии.

Диагностика: плагин help

Когда сборка ведёт себя неожиданно, сначала смотрят, что Maven реально получил на вход: итоговый POM, настройки, активные профили и привязки целей. Всё это показывает maven-help-plugin, и ни одна его цель не запускает сборку.

Пример для скрипта сборки (параметр forceStdout есть в maven-help-plugin 3.1.0 и новее):

VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
echo "$VERSION"
# Output: 1.0-SNAPSHOT

Многомодульный проект

В многомодульном проекте команды запускают из корня, а часть модулей выбирают ключами reactor: -pl — какие модули, -am — плюс модули, от которых они зависят, -amd — плюс модули, которые зависят от них. Без -am соседние модули берутся из ~/.m2, то есть в старой версии.

Создание проекта и Maven Wrapper

Новый проект создают целью archetype:generate, а версию Maven для всей команды фиксируют Maven Wrapper: после mvn wrapper:wrapper проект собирают скриптом ./mvnw, который сам скачивает нужную версию Maven.

Полезные ключи mvn

Ключи пишут до или после фаз в любом порядке. Для CI типичный набор — -B (без интерактивных вопросов и цветного вывода) и -ntp (без строк о скачивании): mvn -B -ntp clean verify. Полный список выводит mvn -h.

Ключи, которые нужны в каждом запуске проекта, кладут в файл .mvn/maven.config в корне проекта (надёжнее всего — по одному аргументу на строку, например -ntp и -Dstyle.color=always). Параметры JVM самого Maven (память, кодировка) задают переменной окружения MAVEN_OPTS, например MAVEN_OPTS="-Xmx2g", или файлом .mvn/jvm.config.

Частые ошибки Maven и их решение

Почти любая ошибка Maven начинается со строки [ERROR] Failed to execute goal или с ошибки чтения POM до начала сборки. В первой строке уже есть всё главное: какой плагин и какая цель упали, в каком модуле и почему. Подробности дают повторный запуск с -e (стек исключения) и -X (отладочный лог).

Пример (примерный вид для Maven 3.9.x; путь и номер строки зависят от проекта):

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project shop-web: Compilation failure
[ERROR] /home/user/shop/shop-web/src/main/java/com/examclouds/web/App.java:[12,9] cannot find symbol
...
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.

Как читать: maven-compiler-plugin:3.13.0:compile — плагин, его версия и цель; (default-compile) — id выполнения: префикс default- означает стандартную привязку к фазе, default-cli — цель вызвана из командной строки, другое имя — execution из вашего pom.xml; on project shop-web — модуль; после двоеточия — причина. Следующие строки уточняют причину, а для многомодульной сборки в конце есть подсказка -rf :shop-web. Тексты сообщений в таблице ниже сокращены, точная формулировка зависит от версии Maven и плагина.