SoFunction
Updated on 2025-05-06

Solution to the problem of Maven image configuration causing dependency download failure

introduction

In project development, using Maven to manage dependencies is a common practice. Maven's dependencies are usually fromRepositoryThere are two main types:Central warehouse(Central Repository) andCompany private warehouse. The central warehouse is officially maintained by Maven and hosts a large number of open source dependencies, but because it is located on the external network, it is often slow to access domestically or even unable to connect. Therefore, many developers will configureMirrorTo speed up dependency downloads. However, when configuring the image, you may encounter problems that dependencies cannot be downloaded, especially setting the image to a wildcard*hour. This article will analyze this problem in depth and provide solutions.

What is a Maven mirror?

Maven mirror is a proxy server that replaces the original repository address and provides faster dependency download services. The mirror server caches dependencies in the original repository and provides services locally or closer network locations to speed up downloads. in the country, commonly used mirrors include Maven mirror warehouses provided by Alibaba Cloud, Huawei Cloud, etc.

Configuration files in MavenIn, can be passed<mirrors>Tag configuration mirroring. For example:

<mirror>
    <id>aliyun</id>
    <name>Aliyun Mirror</name>
    <url>/repository/public</url>
    <mirrorOf>*</mirrorOf>
</mirror>

Here<mirrorOf>Specifies the scope of the warehouse to which the mirror applies.*Indicates that the image will proxy all warehouses, including central warehouses and company private warehouses.

Problem scenario: Dependency cannot be downloaded

Suppose you have a mirror configured in the project.<mirrorOf>Set as*, hope all dependencies will be downloaded through this image. However, runmvn installWhen Maven reported an error, prompting that some dependencies could not be found. You checked the central warehouse and found that these dependencies do exist. What's going on?

Cause of the problem

The root of the problem lies in the coverage of the mirror and the synchronization capability of the mirror repository:

  • MirrorOf=*) ：
    when<mirrorOf>*</mirrorOf>When configured, Maven redirects all repositories' requests (including central repositories and corporate private repositories) to the image. This means that Maven no longer directly accesses the original repository, but relies entirely on dependencies provided by the mirror.
  • Mirror synchronization is incomplete：
    Mirror repositories usually synchronize dependencies from central repositories regularly, but synchronization may be incomplete. Some newer dependencies, unpopular dependencies, or just released dependencies may not have been cached in the mirror repository. If Maven only accesses the image, and these dependencies are missing in the image, the download will fail.
  • The company's private warehouse is covered：
    If your project also relies on a company's private repository (such as Nexus or Artifactory),<mirrorOf>*</mirrorOf>Redirect requests from private repository to the mirror as well. Since mirrors usually do not synchronize dependencies in private repositories, this can also cause private dependencies to be downloaded.

Why does it work properly if configured as central?

When you<mirrorOf>Set ascentralWhen the image only represents the request from the central warehouse, while other warehouses (such as the company's private warehouse) will still directly access the original address. The advantages of this configuration are:

  • Requests from central warehouses are accelerated through mirroring, avoiding bottlenecks in external network access.
  • Requests from the company's private repository will not be overwritten by the mirror, and Maven can download dependencies directly from the private repository.
  • If the dependencies of some central repositories are missing in the image, Maven does not fail completely because requests from private repositories and other repositories are still normal.

For example:

<mirror>
    <id>aliyun</id>
    <name>Aliyun Mirror</name>
    <url>/repository/public</url>
    <mirrorOf>central</mirrorOf>
</mirror>

This configuration explicitly specifies that only the central repository iscentral) and other warehouses remain as they are.

Solution

In order to solve the dependency download problem caused by mirror configuration, the following solutions can be adopted:

1. Precisely configure the mirror, only proxy the central warehouse

Will<mirrorOf>Set ascentral, only let the mirror proxy the requests of the central repository. This can speed up the download of the central warehouse while retaining direct access to the company's private warehouse.

<mirrors>
    <mirror>
        <id>aliyun</id>
        <name>Aliyun Mirror</name>
        <url>/repository/public</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
</mirrors>

existor, ensure that the company's private warehouse is configured correctly, such as:

<repositories>
    <repository>
        <id>company-repo</id>
        <url>/repository/maven-public/</url>
    </repository>
</repositories>

2. Configure multiple images to handle different repositories separately

If your project needs access to multiple repositories, you can configure independent mirrors for each repository. For example, configure Alibaba Cloud Image for the central warehouse and configure internal agent for the company's private warehouse:

<mirrors>
    <mirror>
        <id>aliyun</id>
        <name>Aliyun Mirror</name>
        <url>/repository/public</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
    <mirror>
        <id>company-mirror</id>
        <name>Company Mirror</name>
        <url>/repository/maven-public/</url>
        <mirrorOf>company-repo</mirrorOf>
    </mirror>
</mirrors>

3. Disable mirroring and prioritize the use of private repositories

If the synchronization problem of mirroring occurs frequently, you can consider disabling the mirroring and directly using the company's private repository (usually a proxy for the central repository). existRemove or comment out<mirrors>configuration and inAdd private repository to:

<repositories>
    <repository>
        <id>company-repo</id>
        <url>/repository/maven-public/</url>
    </repository>
</repositories>

Company private repositories are usually configured to proxy central repositories, so most dependencies can be obtained through private repositories.

4. Check the availability of mirrors

Make sure the mirror address used is valid and synchronized properly. For example, access the URL of the image (e.g./repository/public), check whether it can load normally. If the image is not available, you can replace other images (such as Huawei Cloud or Tencent Cloud).

5. Use Maven's --no-mirror parameter

During debugging, you can temporarily disable the mirroring through command line parameters, forcing Maven to directly access the original repository:

mvn install -U --no-mirror

This can help you confirm if the problem is caused by the mirror.

Summarize

In Maven projects, configuring mirroring can significantly improve dependency download speeds, but improper configuration (especially<mirrorOf>*</mirrorOf>) may cause dependencies to be unable to download. The core of the problem is incomplete synchronization of the mirror and unexpected overwrite of private repositories. By<mirrorOf>Set ascentral, can effectively solve this problem while retaining access to private repositories. In addition, it is also a feasible solution to rationally configure multiple images, check the availability of images, or prioritize the use of private repositories.

The above is the detailed content of the solution to the problem of Maven image configuration causing dependency download failure. For more information about Maven dependency download failure, please pay attention to my other related articles!