Виды репозиториев Maven: локальный, Maven Central и корпоративный

На ноутбуке разработчика модуль shop-web собирается без ошибок, а на CI-сервере та же команда mvn package падает с сообщением Could not find artifact com.examclouds:shop-core:jar:1.0-SNAPSHOT in central (https://repo.maven.apache.org/maven2). Код одинаковый, разница в репозиториях: shop-core когда-то установили командой mvn install в локальный репозиторий ~/.m2/repository ноутбука. На CI-сервере локальный репозиторий пуст, а в Maven Central такого артефакта нет. Ниже разберём, где Maven ищет артефакты и как сделать так, чтобы их видели все участники команды.

Репозиторий Maven (Maven repository) — это хранилище артефактов с фиксированной структурой каталогов, из которого Maven берёт зависимости и плагины и в которое публикует результаты сборки. Артефакт — файл, который адресуется координатами Maven: jar, war, pom-файл, архив исходников или Javadoc. Репозитории бывают двух видов: локальный (каталог ~/.m2/repository на вашем компьютере) и удалённые — центральный репозиторий Maven Central, корпоративные (Nexus, Artifactory) и сторонние. Нужный артефакт Maven сначала ищет в локальном репозитории и только потом скачивает из удалённых.

Что хранится в репозитории: артефакты и их адреса

Репозиторий артефактов Maven хранит файлы библиотек и проектов, разложенные по координатам groupId:artifactId:version. Путь к файлу вычисляется из координат: точки в groupId превращаются в каталоги, затем идут каталоги artifactId и версии, а имя файла строится как artifactId-version.расширение. Поэтому локальный, центральный и корпоративный репозитории устроены одинаково.

Например, библиотека с координатами com.google.code.gson:gson:2.11.0 лежит по адресу:

com/google/code/gson/gson/2.11.0/gson-2.11.0.jar
# local:   ~/.m2/repository/com/google/code/gson/gson/2.11.0/gson-2.11.0.jar
# central: https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.jar

Как выбирать сами координаты, разобрано в разделах Координаты GAV и Как выбрать groupId, artifactId и version. В каталоге одной версии обычно лежит несколько файлов:

Виды репозиториев Maven

В Maven есть локальный репозиторий и удалённые. Локальный — кэш на диске разработчика, в нём Maven ищет артефакты в первую очередь. Удалённые доступны по сети: это центральный репозиторий Maven Central (подключён по умолчанию), корпоративный репозиторий компании и сторонние публичные репозитории. Любой репозиторий, кроме локального, Maven считает удалённым.

Локальный репозиторий ~/.m2/repository

Локальный репозиторий Maven по умолчанию находится в каталоге .m2/repository в домашней папке пользователя: ~/.m2/repository в Linux и macOS, C:\Users\<имя>\.m2\repository в Windows. Он персональный для каждого пользователя и общий для всех его проектов: библиотека, скачанная для одного проекта, повторно не скачивается для другого.

В локальный репозиторий артефакты попадают двумя путями: Maven скачивает их из удалённых репозиториев при сборке, а команда mvn install кладёт туда результат сборки вашего проекта — jar (или war, pom, в зависимости от значения packaging) вместе с его POM. После этого другие ваши проекты на этой машине могут подключить его как обычную зависимость. Фрагмент каталога после сборки проекта с Gson и mvn install проекта com.examclouds:shop:

~/.m2/repository/
├── com/
│   ├── examclouds/shop/1.0-SNAPSHOT/      # installed by mvn install
│   │   ├── shop-1.0-SNAPSHOT.jar
│   │   ├── shop-1.0-SNAPSHOT.pom
│   │   ├── maven-metadata-local.xml
│   │   └── _remote.repositories
│   └── google/code/gson/gson/2.11.0/       # downloaded from central
│       ├── gson-2.11.0.jar
│       ├── gson-2.11.0.jar.sha1
│       ├── gson-2.11.0.pom
│       ├── gson-2.11.0.pom.sha1
│       └── _remote.repositories
└── org/apache/maven/plugins/...            # plugins are artifacts too

Обратите внимание на последнюю строку: плагины Maven (maven-compiler-plugin, maven-surefire-plugin) — такие же артефакты, поэтому первая сборка даже пустого проекта скачивает десятки файлов. Сколько займёт каталог, зависит от проектов; на рабочей машине это часто несколько гигабайт. Удалять его безопасно: Maven скачает нужное заново, а установленные через mvn install собственные модули придётся установить повторно.

Как изменить путь. Постоянно — элементом <localRepository> в settings.xml, для одного запуска — системным свойством:

mvn package -Dmaven.repo.local=/tmp/m2-clean

Отдельный пустой каталог удобен, чтобы проверить, соберётся ли проект «с нуля», как на CI-сервере: так ловится ситуация из начала урока.

Центральный репозиторий Maven Central

Maven Central — публичный репозиторий, который Maven использует по умолчанию: он объявлен во встроенном Super POM под id central с адресом https://repo.maven.apache.org/maven2. В нём опубликованы практически все Java-библиотеки и фреймворки с открытым исходным кодом, поэтому для большинства проектов настраивать репозитории не нужно.

Так центральный репозиторий объявлен в Super POM (его можно увидеть в выводе mvn help:effective-pom):

<repositories>
    <repository>
        <id>central</id>
        <name>Central Repository</name>
        <url>https://repo.maven.apache.org/maven2</url>
        <layout>default</layout>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Положить туда свой артефакт напрямую нельзя. Публикация идёт через Central Portal компании Sonatype, и при ней проверяется не код библиотеки, а формальные требования: право на namespace (groupId подтверждается владением доменом или аккаунтом, например io.github.username), наличие архивов исходников и Javadoc, подписи PGP и метаданные в POM (name, description, url, лицензия, разработчики, scm). Опубликованный релиз неизменен: его нельзя ни перезаписать, ни удалить, исправление выпускают новой версией. SNAPSHOT-версии в Maven Central не публикуются, поэтому в Super POM у central они отключены.

Поиск библиотек. Официальный поиск по Maven Central — central.sonatype.com (старый адрес search.maven.org). Популярный сайт mvnrepository.com — неофициальный каталог: он индексирует Central и некоторые другие репозитории, но сам артефакты Maven не раздаёт. Как правильно копировать оттуда координаты, описано в уроке Зависимости в Maven.

Центральный репозиторий работает только по HTTPS, а Maven начиная с версии 3.8.1 по умолчанию блокирует любые HTTP-репозитории — подробнее в уроке Что такое Maven.

Как Maven ищет зависимость

Для каждой зависимости и плагина Maven сначала проверяет локальный репозиторий. Если файл там есть (и это не SNAPSHOT, для которого подошло время проверки обновлений), он используется без обращения к сети. Иначе Maven по очереди опрашивает удалённые репозитории, пока один из них не вернёт артефакт, и сохраняет найденный файл в локальный репозиторий.

По документации Maven удалённые репозитории опрашиваются в таком порядке:

1. репозитории из активных профилей settings.xml (глобального, затем пользовательского);
2. репозитории из pom.xml проекта, затем из родительских POM, и последним — central из Super POM;
3. репозитории, объявленные в POM-файлах зависимостей, по пути к нужному артефакту.

Если для репозитория настроено зеркало, запрос уходит на адрес зеркала. В логе сборки скачивание выглядит так:

[INFO] Downloading from central: https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.pom
[INFO] Downloaded from central: https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.pom (11 kB at 52 kB/s)
[INFO] Downloading from central: https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.jar

Слово после from — id репозитория: по нему видно, откуда реально пришёл файл. Повторная сборка таких строк уже не выводит — всё берётся из ~/.m2/repository. SNAPSHOT-зависимости Maven перепроверяет в удалённом репозитории по расписанию updatePolicy (по умолчанию раз в сутки), подробнее — в разделе SNAPSHOT и релиз.

Неудача тоже кэшируется. Если артефакт не нашёлся (опечатка в версии, недоступный репозиторий), Maven записывает в локальный репозиторий служебный файл с отметкой о неудачной попытке (например, *.lastUpdated) и до истечения интервала обновлений в сеть за ним не идёт, даже если вы уже исправили настройки. Сообщение выглядит примерно так (формулировка зависит от версии Maven):

[ERROR] Failure to find com.example:report-lib:jar:1.0.0 in https://repo.maven.apache.org/maven2
was cached in the local repository, resolution will not be reattempted until the update interval
of central has elapsed or updates are forced

Флаг mvn -U package заставляет Maven проверить удалённые репозитории заново. Если не помогло, удалите каталог этой версии в ~/.m2/repository.

Секция repositories в pom.xml

Чтобы Maven искал зависимости не только в Maven Central, в pom.xml добавляют секцию <repositories>: у каждого репозитория указываются уникальный id, адрес url и разрешение скачивать релизы и SNAPSHOT-версии. Для плагинов Maven используется отдельная секция <pluginRepositories> с теми же элементами.

<repositories>
    <repository>
        <id>company-public</id>
        <url>https://nexus.example.com/repository/maven-public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <id>company-public</id>
        <url>https://nexus.example.com/repository/maven-public/</url>
    </pluginRepository>
</pluginRepositories>

Объявлять central в своём pom.xml не нужно: он и так приходит из Super POM. Значения updatePolicy: always, daily (по умолчанию), interval:N (минуты), never.

Указывать репозитории в pom.xml оправданно для открытого проекта, которому нужен сторонний публичный репозиторий: тогда проект соберётся у любого, кто его скачает. Внутри компании адрес корпоративного репозитория обычно задают не в каждом проекте, а один раз — зеркалом в settings.xml. Логины и пароли в pom.xml не пишут никогда: файл попадает в Git.

settings.xml: зеркала, логины и путь к репозиторию

settings.xml — файл настроек Maven на конкретной машине, а не в проекте: пользовательский ~/.m2/settings.xml и глобальный conf/settings.xml в каталоге установки Maven (при совпадении настроек побеждает пользовательский). В нём задают путь к локальному репозиторию, зеркала удалённых репозиториев, логины и пароли, прокси и профили с дополнительными репозиториями.

Типичный ~/.m2/settings.xml разработчика в компании: все запросы идут через корпоративный репозиторий, а учётные данные берутся из переменных окружения, чтобы пароль не лежал в файле открытым текстом:

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
    <localRepository>D:/maven/repository</localRepository>

    <mirrors>
        <mirror>
            <id>company-nexus</id>
            <name>Company Nexus</name>
            <url>https://nexus.example.com/repository/maven-public/</url>
            <!-- all repositories, including central -->
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

    <servers>
        <server>
            <!-- id must match the mirror or repository id -->
            <id>company-nexus</id>
            <username>${env.NEXUS_USER}</username>
            <password>${env.NEXUS_PASSWORD}</password>
        </server>
    </servers>
</settings>

Значения mirrorOf: * — все репозитории; central — только Maven Central; external:* — все, кроме локальных адресов (localhost, file://); список через запятую с исключениями, например *,!jitpack. Пароли в settings.xml можно также зашифровать командой mvn --encrypt-password (нужен мастер-пароль в ~/.m2/settings-security.xml). Какой файл настроек реально применился, показывает mvn help:effective-settings.

Корпоративный репозиторий: Nexus и Artifactory

Корпоративный репозиторий — удалённый репозиторий, который компания разворачивает на своём сервере, чтобы хранить собственные артефакты и кэшировать публичные. Содержимое и доступ к нему вы полностью контролируете, как в локальном репозитории, но он общий для всей команды и CI-серверов. Самые распространённые решения — Sonatype Nexus Repository и JFrog Artifactory; Maven-репозитории также предоставляют GitHub Packages, GitLab Package Registry и облачные сервисы.

Внутри такого сервера обычно настраивают репозитории трёх типов (названия — как в Nexus, в Artifactory аналогично: local, remote, virtual):

Что даёт корпоративный репозиторий:

• Обмен внутренними библиотеками. Модуль shop-core из начала урока публикуется командой mvn deploy и становится доступен всем разработчикам и CI-серверу.
• Закрытость кода. Доступ ограничивается учётными записями и правами на сервере, артефакты не выходят за пределы компании.
• Скорость и устойчивость. Библиотеки из Central скачиваются из сети компании один раз, сборки не зависят от доступности интернета и внешних серверов.
• Контроль. Можно запретить скачивание библиотек с известными уязвимостями или неподходящими лицензиями (функции зависят от продукта и редакции).

Разработчику для подключения обычно достаточно настроить зеркало и server в settings.xml, как в примере выше, а для публикации — добавить в проект <distributionManagement>.

mvn install и mvn deploy: куда попадает артефакт

Команда mvn install собирает проект и копирует артефакт с его POM в локальный репозиторий — он становится доступен только другим проектам на этом компьютере. Команда mvn deploy выполняет то же самое и дополнительно загружает артефакт в удалённый репозиторий из <distributionManagement>, откуда его получат коллеги и CI-серверы.

Куда публиковать, задаётся отдельно для релизов и SNAPSHOT-версий; Maven выбирает репозиторий по суффиксу версии проекта:

<distributionManagement>
    <repository>
        <id>company-releases</id>
        <url>https://nexus.example.com/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
        <id>company-snapshots</id>
        <url>https://nexus.example.com/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

mvn deploy
# Output (fragment):
[INFO] Uploading to company-snapshots: https://nexus.example.com/repository/maven-snapshots/com/examclouds/shop/1.0-SNAPSHOT/shop-1.0-20261107.101530-1.jar
[INFO] Uploaded to company-snapshots: https://nexus.example.com/repository/maven-snapshots/com/examclouds/shop/1.0-SNAPSHOT/shop-1.0-20261107.101530-1.jar (12 kB at 40 kB/s)
[INFO] BUILD SUCCESS

Для логина Maven ищет в settings.xml элемент <server> с id company-snapshots (или company-releases для релиза). Что выводит mvn install и в каком порядке выполняются фазы до install и deploy, описано в уроках Как установить Maven и Жизненный цикл сборки Maven.

Частые ошибки при работе с репозиториями

Большинство проблем с репозиториями Maven сводится к трём причинам: артефакт есть только в чьём-то локальном репозитории, Maven обращается не к тому репозиторию (из-за зеркала или кэша неудачи) или у него нет прав на доступ. Текст ошибки обычно содержит id репозитория — с него и начинайте диагностику.