Maven Repositories

In Maven terminology, a repository is a location.

A Maven repository is where third-party libraries used in a project are stored. This location is called a repository.

In Maven, any dependency, plugin, or output from a project build can be referred to as an artifact.

Maven repositories help manage artifacts (primarily JARs). They are the places where all JAR files (WAR, ZIP, POM, etc.) are stored.

Maven Repository Types:

Repository Type	Storage Location	Purpose	Access Priority
Local Repository	`.m2/repository` under the user directory	Caches dependencies downloaded from remote repositories	1
Remote Repository	Network server	Provides centralized storage for dependencies and plugins	2
- Central Repository	`repo.maven.apache.org`	Default repository maintained by the Maven community	2.1
- Private Repository	Set up internally within a company (e.g., Nexus)	Hosts private dependencies, accelerates builds	2.2
- Other Public Repositories	Such as Alibaba Cloud, JCenter, etc.	Mirrors or supplements the central repository	2.3

Local Repository

The Maven local repository is not created upon installing Maven. It is created the first time a Maven command is executed.

When Maven runs, it fetches any required artifacts directly from the local repository. If an artifact is not found locally, Maven will first attempt to download it from a remote repository to the local repository, and then use the artifact from the local repository.

By default, regardless of whether you are on Linux or Windows, each user has a repository directory named .m2/repository/ under their user directory.

Windows: C:Users<username>.m2repository
Linux/macOS: ~/.m2/repository

The Maven local repository is created by default in the %USER_HOME% directory. To change the default location, define another path in Maven's settings.xml file located in the %M2_HOME%conf directory.

<settings>
  <localRepository>C:/MyLocalRepository</localRepository>
</settings>

When you run a Maven command, Maven will download the dependent files to the path you specified.

Clean local repository:

mvn dependency:purge-local-repository # Or manually delete the ~/.m2/repository directory

Central Repository

The Maven Central Repository is provided by the Maven community and contains a large number of commonly used libraries.

The central repository contains the vast majority of popular open-source Java artifacts, along with source code, author information, SCM, information, license information, etc. Generally, artifacts needed for simple Java projects can be downloaded from here.

Key concepts of the central repository:

This repository is managed by the Maven community.
No configuration is required.
Access requires a network connection.

Default address for the central repository (no explicit configuration needed): https://repo.maven.apache.org/maven2/

Remote Repository

Custom Repository Configuration

If Maven cannot find the required files in the central repository, it will stop the build process and output an error message to the console. To avoid this, Maven provides the concept of a remote repository, which is a custom repository set up by developers containing the required code libraries or JAR files used in other projects.

For example, using the following pom.xml, Maven will download the dependencies declared in this pom.xml (which are not available in the central repository) from the remote repository.

Example

<repositories>
  <repository>
    <id>aliyun</id>
    <name>Aliyun Maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled><!-- Disable SNAPSHOT versions -->
    </snapshots>
  </repository>
</repositories>

Mirror Repository (Recommended)

Configure in settings.xml:

Example

<mirrors>
  <mirror>
    <id>aliyun</id>
    <name>Aliyun Mirror</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf><!-- Override the central repository -->
  </mirror>
</mirrors>

Maven Alibaba Cloud (Aliyun) Repository

Maven repositories are located overseas by default, which can be slow when used domestically. We can switch to the Alibaba Cloud repository.

Modify the settings.xml file in the conf folder under the Maven root directory. Add the following content under the <mirrors> node:

<mirror>
  <id>aliyunmaven</id>
  <mirrorOf>*</mirrorOf>
  <name>Alibaba Cloud Public Repository</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

If you want to use other proxy repositories, you can add the corresponding repository addresses in the <repositories> node. For example, to use the Spring proxy repository:

<repository>
  <id>spring</id>
  <url>https://maven.aliyun.com/repository/spring</url>
  <releases>
    <enabled>true</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>

Add the information of the files you want to reference in the <dependencies> node of your pom.xml file:

<dependency>
  <groupId></groupId>
  <artifactId></artifactId>
  <version></version>
</dependency>

Execute the pull command:

mvn install

Gradle Configuration Guide

Add the following code to the build.gradle file:

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public/' }
        mavenLocal()
        mavenCentral()
    }
}

If you want to use other proxy repositories, for example, the Spring repository, the code is as follows:

allProjects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/spring/' }
        mavenLocal()
        mavenCentral()
    }
}

Add the information of the files you want to reference:

dependencies {
    compile '::'
}

Execute the following command to install dependencies:

gradle dependencies
# or
./gradlew dependencies

Private Repository

Repository Types:

Repository Type	Purpose
hosted	Stores private artifacts
proxy	Proxies remote repositories
group	Aggregates multiple repositories

Publishing to a Private Repository

Configure in pom.xml:

<distributionManagement>
  <repository>
    <id>nexus-releases</id>
    <url>http://your-nexus/repository/maven-releases</url>
  </repository>
  <snapshotRepository>
    <id>nexus-snapshots</id>
    <url>http://your-nexus/repository/maven-snapshots</url>
  </snapshotRepository>
</distributionManagement>

Configure authentication in settings.xml:

<servers>
  <server>
    <id>nexus-releases</id>
    <username>deploy-user</username>
    <password>deploy-pwd</password>
  </server>
</servers>

Publish command:

mvn deploy

Maven Dependency Search Order

When we execute a Maven build command, Maven starts searching for dependent libraries in the following order:

Step 1 - Search in the local repository. If not found, proceed to Step 2. If found, perform other operations.
Step 2 - Search in the central repository. If not found and one or more remote repositories are configured, proceed to Step 4. If found, download to the local repository for future reference.
Step 3 - If no remote repositories are configured, Maven will simply stop processing and throw an error (unable to find the dependent file).
Step 4 - Search for the dependent file in one or more remote repositories. If found, download to the local repository for future reference. Otherwise, Maven will stop processing and throw an error (unable to find the dependent file).

Common Commands

Command	Purpose
`mvn dependency:resolve`	Resolve dependencies
`mvn dependency:tree`	View dependency tree
`mvn dependency:purge-local-repository`	Clean local repository
`mvn deploy`	Publish to remote repository

Common Problem Solutions

1. Dependency download failure phenomenon: Could not transfer artifact...

Solution:

Check network connection
Verify repository URL is correct
Temporarily disable firewall for testing

2. Authentication failure phenomenon: 401 Unauthorized

Solution:

Check the <server> configuration in settings.xml
Confirm username/password has repository access permissions

3. Dependency conflicts

Investigation:

mvn dependency:tree -Dverbose

Solution: Unify versions in <dependencyManagement>

YouTip