保姆级实战教程:Maven私服Nexus搭建

做Java的同学，一定都遇到过这些痛点：

团队开发时，成员本地 Maven 依赖版本五花八门，频繁出现我本地能跑，你那不行的诡异问题；
新同事入职拉取项目，要等半小时甚至更久下载依赖，速度全靠外网中央仓库的网速随缘；
公司内网环境无法访问外网，项目直接断了「粮」，根本无法完成构建；
团队内部封装了公共工具包，只能手动拷贝 Jar 包导入项目，版本迭代和维护艰难。

而解决这些问题的标准答案，就是搭建一套团队内部的Maven私服。本文就带大家从0到1，完整搭建基于Nexus3的Maven私服，从核心原理到全流程实战，再到踩坑避坑，一篇搞定所有问题。

一、Maven私服核心基础认知

1. 什么是Maven私服

Maven 私服（Repository Manager）本质上是架设在局域网内的私有仓库服务器，核心作用是代理远程公共仓库、管理团队私有构建制品（Jar、War、POM 等文件）。它就像团队内部的 Maven「中转站 + 专属仓库」，所有依赖拉取、制品发布都通过它统一完成。

2. 主流私服产品对比

目前业界主流的 Maven 私服产品有 3 款，特性和适用场景如下：

产品	出品方	核心特点	适用场景
Nexus Repository	Sonatype 公司	业界绝对主流，功能强大，支持 Maven、npm、Docker 等多种制品格式，开源免费版完全满足中小企业需求	绝大多数团队的首选，通用型制品管理
JFrog Artifactory	JFrog 公司	企业级制品仓库，扩展性极强，深度集成 CI/CD 工具，生态完善	中大型企业、复杂 DevOps 流程场景
Apache Archiva	Apache 基金会	轻量级开源工具，仅提供基础的 Maven 仓库管理功能	小型项目、极简需求场景

本文我们选用最主流、生态最完善的 Nexus Repository 3（简称 Nexus3）进行搭建。

3. 私服依赖拉取的完整链路

很多同学只知道用私服，却不了解背后的依赖查找逻辑，理解这个流程，后续出问题才能快速定位。完整的依赖查找链路分为 3 步：

优先查询本地仓库当项目构建需要某个构件时，Maven 会首先检查本地仓库是否存在该构件。如果存在，直接使用，不发起任何远程请求；如果不存在，进入下一步。
请求局域网 Maven 私服本地仓库无对应构件时，请求会直接发送到我们搭建的 Nexus 私服。私服会检查自身仓库：如果有，直接将构件返回给本地 Maven，并存入本地仓库；如果没有，进入下一步。
代理请求外部远程仓库私服中无对应构件时，会根据配置的代理规则，去外部远程仓库（默认 Maven 中央仓库，我们会替换为阿里云镜像）拉取构件。拉取成功后，构件会先缓存到私服中，再返回给本地 Maven 并存入本地仓库。

如果连外部远程仓库都找不到该构件，Maven 才会最终抛出「依赖找不到」的错误。

4. 搭建私服的核心优势

加速构建过程：依赖优先从局域网私服获取，大幅降低外网网络波动带来的影响，构建速度提升数倍；
统一依赖管理：团队所有成员共用一套私服依赖，彻底解决版本不一致问题，减少「环境玄学」问题；
离线构建支持：私服缓存了所有已拉取的依赖，即使断网也能正常完成项目构建，适配内网隔离场景；
私有制品管控：提供统一的私有 Jar 包托管能力，告别手动拷贝 Jar 包的原始方式，实现版本规范化管理；
安全权限管控：支持细粒度的访问控制，仅授权人员可发布 / 拉取制品，保障代码和依赖的安全性。

二、前置环境准备

在开始搭建之前，先确认你的环境满足以下要求，避免后续踩坑：

Java 环境 ：Nexus3 对 Java 版本有严格要求，3.70.x 及以下版本支持 Java 8/Java 11，更高版本建议使用 Java 11，必须提前配置好JAVA_HOME环境变量；
硬件要求：建议至少 2 核 4G 配置，磁盘空间根据团队依赖量预留至少 20G 以上；
系统环境：本文以 Windows 系统为例，Linux 系统的核心配置逻辑完全一致，仅启动脚本不同；
网络要求：服务器能访问外网（用于代理拉取公共依赖），局域网内其他机器能访问该服务器的对应端口（默认 8081）。

三、Nexus3 下载与安装

1. 安装包下载

Nexus 分为专业版和开源 OSS 版，我们使用完全免费的 OSS 版即可，提供两种下载渠道：

官方地址下载：

Download Archives - Sonatype Nexus Repository 3https://help.sonatype.com/en/download-archives---repository-manager-3.html

可根据自己的系统和 Java 版本，选择对应的安装包：Windows 系统选择 win64.zip，Linux/Unix 选择 unixtar.gz。

2. 安装与目录说明

下载完成后，将压缩包解压到非中文、无空格的目录下，解压后会得到两个核心文件夹：

文件夹	核心作用
`nexus-xxx`（xxx 为版本号）	Nexus 安装目录，包含应用程序、启动脚本、配置文件、依赖库等核心内容
`sonatype-work`	Nexus 数据目录，所有仓库的制品、配置、日志、数据库都存储在这里，后续数据备份核心就是备份该文件夹

最好解压到你用来开发的目录下，便于管理。

bin/：Nexus 启动脚本和启动相关配置文件所在目录；
etc/：Nexus 核心配置文件目录；

blobs/：所有构件的二进制文件存储目录；
db/：Nexus 元数据数据库目录；
log/：应用运行日志目录，出问题可在这里查看日志定位。

四、Nexus 启动与初始登录配置

1. 启动 Nexus 服务

进入解压后的nexus-xxx/bin目录，这是启动脚本所在位置；
在文件夹地址栏输入cmd，回车打开命令提示符窗口，会自动定位到当前 bin 目录；
输入启动命令：nexus /run，回车执行（旧版本）。新版本输入 install-nexus-service.bat；添加nexus服务。

注意：首次启动会初始化数据库和配置，耗时较长，请耐心等待，不要关闭命令行窗口。Windows 系统可将 Nexus 配置为系统服务实现后台运行，Linux 系统可使用nexus start命令后台启动。

对应的中文翻译可以看这篇博客：

nexus3.90.x README文档翻译

添加完成后，以终端程序方式启动 nexus:

bash 复制代码

nexus.exe run SonatypeNexusRepository

2. 首次登录与初始设置

打开浏览器，访问地址：http://localhost:8081/（服务器部署则将localhost替换为服务器 IP），即可看到 Nexus 管理页面。首次登录会给你一个密码位置
点击页面右上角的Sign in进行登录，默认用户名为admin；
初始密码获取：老版本默认密码为admin123；新版本的初始密码存放在sonatype-work/nexus3/admin.password文件中，打开该文件即可获取随机初始密码；
首次登录成功后，会引导你修改 admin 账户的密码，按照提示设置新密码即可，后续登录均使用该密码。

然后next就可以了。

五、Nexus 核心仓库类型全解析

登录完成后，点击左侧菜单栏的设置-->Repository，就能看到 Nexus 默认创建的仓库（旧版是在左侧导航栏有一个Browse）。

核心分为 3 种类型，这是 Nexus 最核心的概念，一定要理解清楚：

仓库类型	核心作用	典型默认示例
proxy（代理仓库）	用于代理远程公共仓库，比如 Maven 中央仓库、阿里云镜像。当私服中没有对应依赖时，会从配置的远程地址拉取，并缓存到私服中，后续无需重复请求外网。	maven-central（默认代理 Maven 中央仓库）
hosted（宿主仓库）	用于存放团队内部的私有构件，也就是我们自己开发的 Jar 包。默认分为两个仓库：- maven-releases：存放稳定的发布版构件（Release 版本）- maven-snapshots：存放开发中的快照版构件（Snapshot 版本）	maven-releases、maven-snapshots
group（仓库组）	本身不存储任何构件，核心作用是将多个 proxy 代理仓库、hosted 宿主仓库聚合在一起，对外提供统一的访问地址。本地 Maven 只需配置仓库组的地址，就能同时从聚合的所有仓库中拉取依赖，无需配置多个地址。	maven-public（默认的 Maven 仓库组）

仓库组：maven-public

六、实战配置：阿里云镜像加速，解决外网下载慢问题

默认的 maven-central 仓库代理的是国外 Maven 中央仓库，国内下载速度极慢，甚至会超时失败。这里推荐企业级最佳实践：新增独立的阿里云代理仓库，加入仓库组，不修改默认配置，灵活性更高。

步骤 1：创建阿里云代理仓库

在仓库列表页面，点击右上角的Create repository，创建新仓库；
在仓库类型列表中，选择maven2 (proxy)（Maven 格式的代理仓库）；
进入配置页面，填写核心配置：
- Name：仓库名称，填写aliyun（自定义，方便识别即可）；
- Remote storage：远程存储地址，填写阿里云镜像地址：http://maven.aliyun.com/nexus/content/groups/public/；
- 其他配置保持默认，无需修改；
拉到页面最底部，点击Create repository完成创建。

步骤 2：将阿里云仓库加入公共仓库组

回到仓库列表，点击默认的maven-public仓库组，进入配置页面；
在Group配置的Member repositories区域，将左侧可用仓库中的aliyun，移动到右侧的成员仓库中，并将其调整到最顶部（优先级最高）；
点击Save保存配置，阿里云镜像加速配置完成。

核心原理：仓库组会按照成员仓库从上到下的顺序查找依赖，把阿里云放在最前面，会优先从阿里云镜像拉取依赖，速度大幅提升。

七、本地 Maven 配置，对接私服完成依赖拉取

私服配置完成后，我们需要修改本地 Maven 的核心配置文件settings.xml，让所有 Maven 请求都走我们的私服。

1. 找到配置文件

配置文件位于你的 Maven 安装目录下的conf/settings.xml，例如D:\apache-maven-3.6.3\conf\settings.xml。

2. 配置私服镜像

在settings.xml的<mirrors>标签内，添加如下配置，将所有 Maven 请求都指向我们的私服仓库组：

bash 复制代码

<!-- 配置Nexus私服镜像，拦截所有对central仓库的请求 -->
<mirror>
    <id>nexus-maven</id>
    <!-- mirrorOf设置为central，代表拦截所有中央仓库的请求，也可设置为*拦截所有请求 -->
    <mirrorOf>central</mirrorOf>
    <name>Nexus Private Repository</name>
    <!-- 地址为maven-public仓库组的URL，在Nexus仓库列表中点击copy即可获取 -->
    <url>http://localhost:8081/repository/maven-public/</url>
</mirror>

注意：<id>标签的值必须全局唯一，后续的账号密码配置会通过这个 id 关联。

3. 配置私服访问账号密码

私服默认开启了权限控制，我们需要在settings.xml的<servers>标签内，添加私服的账号密码配置，和上面的镜像 id 关联：

bash 复制代码

<!-- 配置Nexus私服的访问账号密码 -->
<server>
    <!-- 这里的id必须和上面mirror标签中的id完全一致 -->
    <id>nexus-maven</id>
    <!-- Nexus的登录用户名 -->
    <username>admin</username>
    <!-- 你设置的Nexus登录密码 -->
    <password>你的Nexus密码</password>
</server>

4. 验证配置是否生效

保存settings.xml文件后，打开任意一个 Maven 项目，在项目根目录执行命令：

bash 复制代码

mvn clean compile

如果控制台能正常拉取依赖，且日志中显示从我们的私服地址下载构件，就代表配置成功了。此时你拉取的所有依赖，都会被缓存到 Nexus 私服中，后续团队其他成员拉取同一个依赖，直接从私服局域网下载，速度会有质的提升。

八、进阶实战：将私有 Jar 包发布到 Nexus 私服

私服的另一核心价值，就是管理团队内部的私有 Jar 包，下面教大家如何将自己的 Maven 项目打包发布到私服中。

1. 配置项目的 pom.xml 文件

在需要发布的 Maven 项目的pom.xml文件中，添加如下分发管理配置，指定发布到私服的对应仓库：

bash 复制代码

<!-- 配置制品分发仓库，也就是我们的Nexus私服 -->
<distributionManagement>
    <!-- Release发布版仓库 -->
    <repository>
        <id>nexus-maven</id>
        <name>Nexus Release Repository</name>
        <url>http://localhost:8081/repository/maven-releases/</url>
    </repository>
    <!-- Snapshot快照版仓库 -->
    <snapshotRepository>
        <id>nexus-maven</id>
        <name>Nexus Snapshot Repository</name>
        <url>http://localhost:8081/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

关键说明：

这里的<id>必须和settings.xml中server标签的 id 完全一致，才能关联上账号密码；

Maven 会自动根据项目的版本号，判断发布到哪个仓库：版本号带-SNAPSHOT后缀的，会发布到快照仓库；不带的会发布到发布仓库。

2. 执行发布命令

在项目根目录执行 Maven 发布命令：

bash 复制代码

mvn clean deploy

执行成功后，打开 Nexus 管理页面，进入对应的maven-releases或maven-snapshots仓库，就能看到我们发布的私有 Jar 包了。

3. 团队使用私有 Jar 包

其他成员只需按照上述步骤配置好 Maven 对接私服，就可以直接在项目的 pom.xml 中引入这个私有依赖，和引入公共依赖完全一样，无需任何额外配置。

九、踩坑指南：常见问题与解决方案

1. Nexus 启动失败，提示 Java 版本不匹配

问题原因：Nexus 版本和本地 Java 版本不兼容；
解决方案：核对 Nexus 官方的版本要求，3.70.x 及以下使用 Java 8/11，更高版本建议使用 Java 11，配置正确的JAVA_HOME环境变量。

2. 启动成功，但浏览器无法访问 8081 端口

问题原因：端口被占用、防火墙拦截、IP 访问限制；
解决方案：
1. 检查 8081 端口是否被其他程序占用，可在nexus-xxx/etc/nexus.properties文件中修改默认端口；
2. 关闭服务器的防火墙，或放行 8081 端口；
3. 检查 Nexus 配置，是否绑定了 127.0.0.1，修改为 0.0.0.0 允许所有 IP 访问。

3. 执行 mvn 命令时，提示权限不足，无法拉取 / 发布依赖

问题原因：settings.xml中的账号密码错误，或<id>没有和 mirror/repository 的 id 对应；
解决方案：核对账号密码是否正确，确保所有关联的<id>完全一致，检查 Nexus 中对应用户的权限是否正常。

4. 发布 Release 版本时，提示仓库不允许重复发布

问题原因：Nexus 的 maven-releases 仓库默认配置为「不允许重复发布」，同一个 Release 版本号不能多次发布；
解决方案：
1. 最佳实践：每次发布 Release 版本，都升级版本号；
2. 临时方案：修改 maven-releases 仓库的配置，将Deployment policy改为Allow redeploy。

十、写在最后

到这里，我们就完成了从 0 到 1 搭建 Maven 私服 Nexus3 的全流程，从原理认知、安装配置、镜像加速，到本地对接、私有包发布，覆盖了企业级开发的所有核心场景。

Maven 私服不仅解决了依赖下载的速度问题，更重要的是实现了团队依赖的统一管理、私有制品的规范化管控，是企业级 DevOps 流程中不可或缺的一环。后续大家还可以基于 Nexus 扩展更多功能，比如配置细粒度的用户权限、对接 Jenkins 实现自动化构建发布、配置仓库清理策略等等。