Maven国内镜像settings.xml配置大全：阿里云、腾讯云、华为云、清华源

最后更新：2026-05-12
适用系统：Windows / macOS / Linux
适用场景：Maven 下载依赖慢、Could not transfer artifact、IDEA Maven 构建失败、国内网络访问 Maven Central 不稳定

如果你还没有安装 JDK，可以先查看：各版本JDK镜像下载地址：JDK8 / 11 / 17 / 21 / 25 / 26 下载与IDEA配置指南。

在国内使用 Maven，最常见的问题不是代码写错，而是依赖下载失败：

Could not transfer artifact
Could not resolve dependencies
Connection timed out
Read timed out
Transfer failed for https://repo.maven.apache.org/maven2

这些问题很多时候不是项目本身有问题，而是 Maven 访问中央仓库太慢或网络不稳定。解决办法通常很简单：在 settings.xml 中配置国内 Maven 镜像源。

本文整理常用 Maven 国内镜像配置，包括：

阿里云 Maven 镜像
腾讯云 Maven 镜像
华为云 Maven 镜像
清华源 Maven 安装包下载
IDEA 中 Maven settings.xml 配置
Maven 本地仓库配置
常见报错排查

先说结论：普通开发者优先使用阿里云 Maven 镜像；腾讯云服务器优先用腾讯云；华为云服务器优先用华为云；清华源适合下载 Maven 安装包，不建议作为 settings.xml 主依赖镜像长期使用。

一、settings.xml 放在哪里？

Maven 的配置文件叫 settings.xml，常见有两个位置：

Maven全局配置：
<Maven安装目录>/conf/settings.xml

用户级配置：
~/.m2/settings.xml

Windows 示例：

D:\dev\apache-maven-3.9.15\conf\settings.xml
C:\Users\你的用户名\.m2\settings.xml

macOS / Linux 示例：

/opt/apache-maven-3.9.15/conf/settings.xml
~/.m2/settings.xml

建议优先使用用户级配置：

~/.m2/settings.xml

原因很简单：以后升级 Maven 版本时，不会因为替换 Maven 安装目录导致配置丢失。

如果你的 ~/.m2/ 目录下没有 settings.xml，可以从 Maven 安装目录复制一份：

mkdir -p ~/.m2
cp /opt/apache-maven-3.9.15/conf/settings.xml ~/.m2/settings.xml

Windows 用户也可以手动创建：

C:\Users\你的用户名\.m2\settings.xml

二、最推荐的配置：阿里云 Maven 镜像

阿里云 Maven 镜像是国内使用最广的 Maven 公共代理仓库之一。普通开发环境下，如果你不知道选哪个，直接用阿里云即可。

将下面内容保存到：

~/.m2/settings.xml

完整配置如下：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <!-- 本地仓库位置：不配置时默认是 ~/.m2/repository -->
    <localRepository>${user.home}/.m2/repository</localRepository>

    <mirrors>
        <mirror>
            <id>aliyunmaven</id>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

</settings>

配置完成后执行：

mvn -version
mvn help:effective-settings

如果能看到 aliyunmaven，说明配置已经生效。

三、腾讯云 Maven 镜像配置

如果你的项目部署在腾讯云，或者开发机、构建机在腾讯云 CVM 上，可以优先使用腾讯云 Maven 镜像。

settings.xml 配置如下：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <localRepository>${user.home}/.m2/repository</localRepository>

    <mirrors>
        <mirror>
            <id>nexus-tencentyun</id>
            <name>Nexus tencentyun</name>
            <url>https://mirrors.tencent.com/nexus/repository/maven-public/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

</settings>

腾讯云服务器上使用时，腾讯云软件源还可能走更近的网络链路，下载速度通常会更稳定。

四、华为云 Maven 镜像配置

如果你的服务器在华为云，或者项目运行在华为云、鲲鹏、国产化环境中，可以使用华为云 Maven 镜像。

settings.xml 配置如下：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <localRepository>${user.home}/.m2/repository</localRepository>

    <mirrors>
        <mirror>
            <id>huaweicloud</id>
            <name>华为云 Maven 镜像</name>
            <url>https://repo.huaweicloud.com/repository/maven/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

</settings>

华为云官方也提供 Maven 安装包加速地址：

https://repo.huaweicloud.com/apache/maven/maven-3/

如果你还没有安装 Maven，可以先从这个地址下载 Maven 安装包。

五、清华源 Maven 怎么用？

这里要特别说明一下：很多文章会把“清华源 Maven”直接写进 settings.xml，但不建议你把它作为主推荐配置。

清华 TUNA 当前更适合作为 Apache Maven 安装包下载镜像，比如下载 Maven 3.x 安装包：

https://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/

使用方式：

1. 打开清华 Apache Maven 镜像目录
2. 选择 Maven 版本，例如 3.9.x
3. 进入 binaries 目录
4. 下载 apache-maven-版本号-bin.zip 或 apache-maven-版本号-bin.tar.gz
5. 解压后配置环境变量

不建议在生产教程中把清华源写成主要 Maven 依赖镜像，原因是：Maven 依赖下载需要的是 Maven Central 或代理仓库，而清华 TUNA 的 Apache Maven 目录主要是 Apache Maven 项目安装包镜像，不等于 Maven Central 依赖仓库。

如果你只是想下载 Maven 本体，清华源很好用；如果你是想加速项目依赖下载，优先使用阿里云、腾讯云或华为云。

六、不要同时配置多个 mirrorOf="*"

很多人会这样写：

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <url>https://maven.aliyun.com/repository/public</url>
        <mirrorOf>*</mirrorOf>
    </mirror>

    <mirror>
        <id>huaweicloud</id>
        <url>https://repo.huaweicloud.com/repository/maven/</url>
        <mirrorOf>*</mirrorOf>
    </mirror>

    <mirror>
        <id>tencent</id>
        <url>https://mirrors.tencent.com/nexus/repository/maven-public/</url>
        <mirrorOf>*</mirrorOf>
    </mirror>
</mirrors>

这种写法看起来像“多个镜像备用”，但实际并不是你想的那样。

Maven 不会自动按照顺序尝试多个相同 mirrorOf="*" 的镜像。通常情况下，它会选择第一个匹配的 mirror。也就是说，后面的镜像很可能根本不会被用到。

正确做法是：只保留一个主镜像。

例如你想用阿里云，就只写阿里云：

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
        <mirrorOf>*</mirrorOf>
    </mirror>
</mirrors>

如果阿里云暂时不可用，再手动切换成腾讯云或华为云。

七、mirrorOf 应该写 central 还是 *？

常见写法有两种：

<mirrorOf>central</mirrorOf>

和：

<mirrorOf>*</mirrorOf>

区别如下：

写法	含义	适合场景
`central`	只代理 Maven Central	项目还需要访问其他自定义仓库
`*`	代理所有远程仓库请求	普通开发者、简单项目、国内加速
`external:*`	代理所有外部仓库，不代理本地和 file 仓库	企业项目、复杂构建
`*,!repo-id`	代理除某个仓库之外的所有仓库	需要排除公司私服或特殊仓库

普通开发者可以直接用：

<mirrorOf>*</mirrorOf>

如果你的公司有 Nexus、Artifactory、私有 Maven 仓库，建议不要盲目使用 *，而是让公司私服统一代理外部仓库。

八、IDEA 中如何指定 Maven settings.xml？

很多人明明配置了 settings.xml，但 IDEA 里 Maven 还是下载失败，原因通常是 IDEA 没有使用你改过的配置文件。

在 IntelliJ IDEA 中按下面路径检查：

File > Settings > Build, Execution, Deployment > Build Tools > Maven

macOS 是：

IntelliJ IDEA > Settings > Build, Execution, Deployment > Build Tools > Maven

重点检查三个地方：

Maven home path
User settings file
Local repository

推荐配置：

Maven home path：
选择你安装的 Maven 目录，例如 D:\dev\apache-maven-3.9.15

User settings file：
选择 C:\Users\你的用户名\.m2\settings.xml

Local repository：
选择 C:\Users\你的用户名\.m2\repository

配置完成后，点击：

Reload All Maven Projects

如果项目还是下载失败，可以执行：

mvn help:effective-settings

确认 Maven 实际读取的是哪个 settings.xml。

九、Maven 本地仓库 localRepository 怎么配置？

Maven 下载过的依赖会缓存在本地仓库中。默认路径是：

~/.m2/repository

Windows 上通常是：

C:\Users\你的用户名\.m2\repository

如果你的 C 盘空间不够，可以改到其他磁盘：

<localRepository>D:/dev/maven/repository</localRepository>

完整示例：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <localRepository>D:/dev/maven/repository</localRepository>

    <mirrors>
        <mirror>
            <id>aliyunmaven</id>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

</settings>

注意：路径中尽量不要包含中文、空格和特殊符号。

不推荐：

D:/我的开发工具/Maven 仓库/

十、如何验证 Maven 镜像是否生效？

1. 查看 Maven 版本

mvn -version

正常输出类似：

Apache Maven 3.9.15
Java version: 17.x.x

如果提示 mvn 不是内部或外部命令，说明 Maven 环境变量没有配置好。

2. 查看实际 settings.xml

mvn help:effective-settings

如果你配置的是阿里云，输出中应该能看到：

<id>aliyunmaven</id>
<url>https://maven.aliyun.com/repository/public</url>

如果看不到，说明 Maven 没有读取你修改的 settings.xml。

3. 强制更新依赖

mvn clean package -U

-U 表示强制检查远程依赖更新，适合排查依赖缓存问题。

4. 删除失败缓存

有时候 Maven 下载失败后，会在本地仓库留下 .lastUpdated 文件，导致后续一直失败。

可以删除这些文件：

Linux / macOS：

find ~/.m2/repository -name "*.lastUpdated" -delete

Windows PowerShell：

Get-ChildItem "$env:USERPROFILE\.m2\repository" -Recurse -Filter "*.lastUpdated" | Remove-Item

然后重新执行：

mvn clean package -U

十一、常见报错解决

1. Could not transfer artifact

常见原因：

网络连接 Maven Central 不稳定
镜像源暂时不可用
公司网络代理限制
settings.xml 没有生效
本地仓库存在失败缓存

解决方法：

1. 检查 settings.xml 是否配置国内镜像
2. 执行 mvn help:effective-settings
3. 删除 .lastUpdated 文件
4. 执行 mvn clean package -U
5. 换一个镜像源测试

2. Could not resolve dependencies

常见原因：

依赖版本写错
依赖不存在于 Maven Central
镜像源没有同步该依赖
项目需要额外仓库
本地缓存损坏

解决方法：

1. 检查 groupId、artifactId、version 是否正确
2. 到 Maven Central 或 mvnrepository 查询依赖是否存在
3. 删除对应依赖目录后重新下载
4. 如果是私有依赖，确认公司私服配置是否正确

例如删除某个依赖缓存：

rm -rf ~/.m2/repository/com/example/demo

Windows 可手动删除：

C:\Users\你的用户名\.m2\repository\com\example\demo

3. PKIX path building failed

这是 SSL 证书相关问题，通常不是 Maven 镜像本身的问题。

常见原因：

公司网络使用 HTTPS 代理
JDK 证书库缺少公司根证书
镜像源证书被代理替换
使用了过旧 JDK

解决方向：

1. 换用公司网络外的环境测试
2. 检查是否需要配置代理
3. 让运维提供公司根证书
4. 将证书导入 JDK cacerts
5. 升级 JDK 版本

4. IDEA 能下载，命令行不能下载

常见原因：

IDEA 使用的是内置 Maven 或单独配置的 Maven
命令行使用的是另一个 Maven
IDEA 和命令行读取的 settings.xml 不一样
JAVA_HOME 不一致

排查命令：

mvn -version
mvn help:effective-settings

IDEA 中检查：

Settings > Build Tools > Maven

重点看：

Maven home path
User settings file
Local repository
JDK for importer

5. 命令行能下载，IDEA 不能下载

优先检查 IDEA 的 Maven 配置：

1. IDEA 是否使用了正确的 Maven home
2. IDEA 是否指定了正确的 User settings file
3. IDEA 的 Local repository 是否和命令行一致
4. 修改 settings.xml 后是否 Reload Maven
5. 是否开启了 Work offline

如果 IDEA 开启了离线模式，也会导致依赖下载失败。

十二、企业项目建议使用 Maven 私服

如果是公司项目，不建议每个人都直接连阿里云、腾讯云、华为云镜像。

更好的方式是搭建公司内部 Maven 私服，例如：

Nexus Repository
JFrog Artifactory
Apache Archiva

推荐链路：

开发者 Maven
    ↓
公司 Nexus / Artifactory
    ↓
阿里云 / 腾讯云 / 华为云 / Maven Central

这样做有几个好处：

1. 公司内部依赖可以统一管理
2. 外部依赖可以缓存，减少重复下载
3. 可以控制依赖版本，降低供应链风险
4. CI/CD 构建速度更稳定
5. 离职、换电脑、换网络环境影响更小

企业内部 settings.xml 示例：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <localRepository>${user.home}/.m2/repository</localRepository>

    <mirrors>
        <mirror>
            <id>company-nexus</id>
            <name>Company Nexus Repository</name>
            <url>https://nexus.example.com/repository/maven-public/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

    <servers>
        <server>
            <id>company-nexus</id>
            <username>你的用户名</username>
            <password>你的密码或Token</password>
        </server>
    </servers>

</settings>

注意：如果要连接公司私服，server 的 id 要和仓库或 mirror 的 id 对应。

十三、Maven 国内镜像地址汇总

镜像源	推荐用途	地址
阿里云 Maven	普通开发者首选	`https://maven.aliyun.com/repository/public`
腾讯云 Maven	腾讯云服务器、腾讯云环境	`https://mirrors.tencent.com/nexus/repository/maven-public/`
华为云 Maven	华为云、鲲鹏、国产化环境	`https://repo.huaweicloud.com/repository/maven/`
清华 Apache Maven	下载 Maven 安装包	`https://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/`
Maven Central 官方仓库	官方中央仓库	`https://repo.maven.apache.org/maven2`

我的建议：

个人电脑：阿里云 Maven
腾讯云服务器：腾讯云 Maven
华为云服务器：华为云 Maven
公司项目：公司 Nexus / Artifactory
下载 Maven 安装包：清华源或华为源

十四、FAQ

1. Maven 国内镜像会不会导致依赖版本不一致？

一般不会。Maven 依赖有 groupId、artifactId、version 坐标，正常情况下同一个版本的依赖应该一致。

但镜像源可能存在同步延迟。如果你刚发布了一个新版本依赖，或者某个依赖刚同步到 Maven Central，国内镜像可能需要等一段时间才能访问。

如果遇到新版本依赖下载不到，可以临时切回 Maven Central 或公司私服。

2. settings.xml 和 pom.xml 都能配置仓库，应该改哪个？

普通用户优先改：

~/.m2/settings.xml

不要随便在项目 pom.xml 里写国内镜像地址。原因是 pom.xml 是项目文件，会提交到代码仓库。如果你把个人网络环境相关配置写进项目，其他同事、CI/CD、海外服务器可能会受影响。

推荐做法：

个人下载加速：settings.xml
项目必须依赖的特殊仓库：pom.xml
公司统一仓库：settings.xml + 公司私服

3. Maven 镜像和 Maven 私服有什么区别？

Maven 镜像主要是加速公共依赖下载，比如代理 Maven Central。

Maven 私服除了加速，还能管理公司内部依赖，例如：

公司内部 SDK
业务公共包
二方库
私有插件
SNAPSHOT 版本
Release 版本

个人开发用镜像就够了；公司团队建议上私服。

4. Maven 3.9 和 Maven 4 应该用哪个？

普通项目建议继续使用 Maven 3.9.x。

Maven 4 还处于预览或候选阶段时，不建议直接用于生产项目。除非你明确要测试 Maven 4 的新特性，否则优先使用 Maven 3.9.x。

5. Maven 需要配置 JAVA_HOME 吗？

建议配置。

Maven 运行需要 JDK。配置好后执行：

mvn -version

正常情况下会显示 Maven 版本和 Java 版本。如果 Java 版本不对，说明 JAVA_HOME 或 PATH 可能配置错了。

6. 为什么配置了镜像还是下载很慢？

可能原因：

1. settings.xml 没有被 Maven 读取
2. IDEA 使用了另一个 settings.xml
3. 镜像源当前同步或网络异常
4. 公司代理限制 HTTPS 访问
5. 本地仓库存在损坏缓存
6. 依赖来自特殊仓库，不在公共 Maven 镜像里

排查顺序：

mvn help:effective-settings
mvn clean package -U

然后检查 IDEA Maven 配置和本地仓库缓存。

十五、最终推荐配置

如果你只是想快速解决 Maven 下载慢的问题，直接复制这一份即可：

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <localRepository>${user.home}/.m2/repository</localRepository>

    <mirrors>
        <mirror>
            <id>aliyunmaven</id>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>

</settings>

如果你在腾讯云，把 mirror 换成腾讯云：

<mirror>
    <id>nexus-tencentyun</id>
    <name>Nexus tencentyun</name>
    <url>https://mirrors.tencent.com/nexus/repository/maven-public/</url>
    <mirrorOf>*</mirrorOf>
</mirror>

如果你在华为云，把 mirror 换成华为云：

<mirror>
    <id>huaweicloud</id>
    <name>华为云 Maven 镜像</name>
    <url>https://repo.huaweicloud.com/repository/maven/</url>
    <mirrorOf>*</mirrorOf>
</mirror>

记住一句话：settings.xml 里不要同时启用多个 mirrorOf="*"，选一个稳定的主镜像即可。

更新记录

2026-05-12：
- 增加阿里云 Maven settings.xml 配置
- 增加腾讯云 Maven settings.xml 配置
- 增加华为云 Maven settings.xml 配置
- 增加清华源 Maven 安装包下载说明
- 增加 IDEA Maven 配置方法
- 增加 mirrorOf 用法说明
- 增加 Could not transfer artifact 常见排查
- 增加企业 Maven 私服建议

如果觉得文章对你有用，请随意赞赏

Maven Maven国内镜像 IDEA Maven配置 Java环境配置

Maven国内镜像settings.xml配置大全：阿里云、腾讯云、华为云、清华源

https://java.li/archives/FtMJgXo1

作者

HiF

发布于

2026-05-12

更新于

2026-05-12

许可协议

CC BY 4.0

一、settings.xml 放在哪里？

二、最推荐的配置：阿里云 Maven 镜像

三、腾讯云 Maven 镜像配置

四、华为云 Maven 镜像配置

五、清华源 Maven 怎么用？

六、不要同时配置多个 mirrorOf="*"

七、mirrorOf 应该写 central 还是 *？

八、IDEA 中如何指定 Maven settings.xml？

九、Maven 本地仓库 localRepository 怎么配置？

十、如何验证 Maven 镜像是否生效？

1. 查看 Maven 版本

2. 查看实际 settings.xml

3. 强制更新依赖

4. 删除失败缓存

十一、常见报错解决

1. Could not transfer artifact

2. Could not resolve dependencies

3. PKIX path building failed

4. IDEA 能下载，命令行不能下载

5. 命令行能下载，IDEA 不能下载

十二、企业项目建议使用 Maven 私服

十三、Maven 国内镜像地址汇总

十四、FAQ

1. Maven 国内镜像会不会导致依赖版本不一致？

2. settings.xml 和 pom.xml 都能配置仓库，应该改哪个？

3. Maven 镜像和 Maven 私服有什么区别？

4. Maven 3.9 和 Maven 4 应该用哪个？

5. Maven 需要配置 JAVA_HOME 吗？

6. 为什么配置了镜像还是下载很慢？

十五、最终推荐配置

更新记录

作者

发布于

更新于

许可协议

评论