企业官网建设流程全解析

1. 先从根上理清楚：继承、聚合、私服到底在解决什么问题

做Java后端开发的人，只要项目一多、模块一拆，迟早会遇到同一个问题：依赖怎么管、版本怎么对齐、构建怎么从一次次手工打包变成一条命令跑完。Maven的高级玩法——继承、聚合、私服，就是专门用来处理这三件事的。我上半年帮某公司内部业务系统做了一次工程化改造，把原本散落的上百个jar包依赖梳理成一套统一管理的多模块工程，这个过程里踩过的坑和沉淀下来的方案，今天完整写一遍。

先说个最粗浅的理解。Maven本身是个构建工具，它管三件事：依赖下载、编译打包、生命周期执行。基础的pom.xml大家都会写，但项目一多、模块一拆，你会发现问题接踵而至——每个模块都各写各的版本号，升级一个中间件版本要全项目搜替换；构建一个包含多个子系统的项目，要手动按顺序逐个打包；公司内部的公共组件，只能靠人肉拷贝jar包到本地仓库再install，传播路径混乱。这些问题的解药就是继承、聚合、私服三个机制。

继承解决的是“公共配置如何复用”，聚合解决的是“多个模块如何协同构建”，私服解决的是“依赖从哪来、公共组件如何分发”。三者可以配合使用，也可以独立使用。实际做工程化改造的时候，它们往往是一套组合拳。后面我会按实际落地的顺序，逐个拆开讲。

2. 聚合工程：让多个模块变成一次构建

2.1 聚合工程的组织方式与目录结构

聚合工程，通俗讲就是一个“壳工程”，它的pom.xml里不写业务代码，只声明子模块列表。构建时你只用敲一条命令，Maven会先读取聚合POM中的<modules>列表，然后按照模块之间的依赖关系自动计算构建顺序。

我们内部系统拆分后的目录结构是这样的：

platform-parent ├── pom.xml ├── platform-common │ └── pom.xml ├── platform-domain │ └── pom.xml ├── platform-service-api │ └── pom.xml ├── platform-service-impl │ └── pom.xml ├── platform-web │ └── pom.xml └── platform-server └── pom.xml

聚合POM里的结构就三块：坐标声明、packaging声明、modules列表。

<groupId>com.dzxt.demo</groupId> <artifactId>platform-parent</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>pom</packaging> <modules> <module>platform-common</module> <module>platform-domain</module> <module>platform-service-api</module> <module>platform-service-impl</module> <module>platform-web</module> <module>platform-server</module> </modules>

注意pom.xml中<packaging>pom</packaging>这行，聚合模块的packaging必须是pom，不能是jar或war。原因很简单：聚合模块本身不产出可运行构件，它只是组织者。这也是很多人第一次搭聚合工程时报错的最常见原因——packaging写错了。

构建顺序不需要你在modules里刻意排，Maven会根据模块间的依赖关系做拓扑排序。比如平台common被其他模块依赖，它会第一个构建；platform-service-impl依赖platform-service-api，那么api先构建。我实际用的命令是：

mvn clean install -pl platform-web,platform-server -am

这里-pl表示只构建指定模块，-am（also make）表示同时构建它们依赖的上游模块。这种用法在只改了一两个模块、不想全量构建时非常省时间。全量构建直接mvn clean install就行，一次把六个模块全部按序打出来。

2.2 聚合与继承必须拆开的误区

很多初学者以为聚合POM就是父POM，直接把<parent>和<modules>塞进同一个pom里。这不算错，但两种场景的职责不同，我建议在工程改造时把“聚合壳工程”和“父POM”分开。

我的做法是：壳工程只负责modules列表，不承载依赖管理；真正承载公共依赖管理的parent POM，作为最顶层模块的父节点存在。这样带来的好处是，如果以后某个Spring Boot版本升级，你只需要改父POM中的dependencyManagement，聚合壳完全不用动。

壳工程还有个隐含作用，就是统一触发构建。如果你把两个独立的子系统放到同一个仓库目录下，用聚合工程包住它们，就能用一个CI任务完成全部构建，避免在持续集成流水线里写很多个Builder步骤。

2.3 聚合工程里的模块依赖关系

模块间依赖关系写清楚很重要，否则构建顺序会乱，或者出现循环依赖。各模块之间依赖要按实际使用关系来声明，比如platform-service-api被platform-service-impl依赖，就在impl的pom里写：

<dependency> <groupId>com.dzxt.demo</groupId> <artifactId>platform-service-api</artifactId> <version>${project.version}</version> </dependency>

这里我用${project.version}而不是硬编码版本号，目的是让所有模块版本完全跟随父版本。以后整体升级版本号时，只改父POM的<version>一处，所有内部模块间的依赖会自动统一版本。这个细节在多人协作项目里非常有用，能避免“两个模块依赖的内部组件版本不一致”这种低级但高发的事故。

模块间依赖有两点要注意：

• 禁止循环依赖，比如A依赖B、B又依赖A，Maven的拓扑排序会直接卡死。
• 内部模块依赖scope一般用默认的compile即可，不需要runtime、provided这类特殊scope。

2.4 聚合工程中一次构建的实操示例

我把改造后的构建过程贴在CI脚本里，实际验证过是稳定的：

#!/bin/bash set -e mvn clean install -DskipTests -q echo "build completed"

加上-DskipTests是跳过单测，编译速度能提升不少。-q参数控制日志输出，只打印错误，避免几百MB的构建日志刷爆控制台。全量install完成之后，每个子模块的target目录下都会生成对应的jar包或war包，platform-server下会生成可直接运行的Spring Boot的jar。

如果只想把某个接口服务发布出去，就用：

mvn clean package -pl platform-server -am -DskipTests -Dmaven.test.skip=true

这里-DskipTests和-Dmaven.test.skip=true的区别是：前者只跳过测试执行，测试代码仍会编译；后者连测试代码都跳过编译。CI打包阶段我会用后者，省时间更彻底。

3. 继承机制：把公共配置沉淀到父POM

3.1 父POM的三个核心职责

在讲私服之前，必须先讲继承。继承机制允许子模块通过<parent>声明继承某个父POM。这个父POM可以是我们自己维护的祖先POM，也可以直接继承Spring Boot官方提供的spring-boot-starter-parent。

父POM的核心职责有四个：

• 依赖版本管理（dependencyManagement）
• 公共属性定义（properties）
• 插件管理（pluginManagement）
• 公共依赖声明（dependencies）

实际项目中，我建议把“公共依赖声明”拆成两种情况：所有模块都必须用的依赖，比如lombok、junit，放在<dependencies>里直接声明；版本可能变动的中间件依赖，放在<dependencyManagement>里只锁版本不引入依赖。这样职责清晰，避免子模块被无谓地填充大量用不到的依赖。

3.2 dependencyManagement与properties配合使用

这是整个继承机制里最核心的用法。我先给一个父POM的骨架：

<properties> <java.version>17</java.version> <spring-boot.version>3.1.5</spring-boot.version> <mysql.version>8.0.33</mysql.version> <mybatis-plus.version>3.5.4.1</mybatis-plus.version> <fastjson2.version>2.0.43</fastjson2.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>${spring-boot.version}</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <version>${mysql.version}</version> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-spring-boot3-starter</artifactId> <version>${mybatis-plus.version}</version> </dependency> <dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2</artifactId> <version>${fastjson2.version}</version> </dependency> </dependencies> </dependencyManagement>

这种写法的巧妙之处在于，properties把版本号集中到了顶部，dependencyManagement用变量引用这些版本号。升级版本时，你只需要在properties里改一行。比如MySQL驱动从8.0.33升到8.0.35，全局只改一处。

子模块中引用这些依赖时，不需要写version：

<dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> </dependency>

Maven会沿着继承链向上找dependencyManagement，命中后自动补全版本号。如果某个子模块就是想用不同版本，也可以显式写<version>覆盖父继承的管理版本。这个机制让“默认统一”和“个别例外”同时成为可能。

3.3 继承链与import scope的区别

说一个很多文章没讲透的细节：<type>pom</type>和<scope>import</scope>的组合。如果你不想让自己的父POM直接继承Spring Boot BOM，而是想把它当依赖管理的“版本字典”导入，就用这个组合。

两者区别很关键。继承spring-boot-starter-parent时，整个构建体系完全以Spring Boot为标准，包括插件执行配置、资源处理行为，这最适合标准Spring Boot项目。而import的方式，只是拿spring-boot-dependencies这个BOM来管理依赖版本，你仍然可以自定义插件管理和各种构建细节。

我实际改造的项目没有直接继承Spring Boot的parent，而是自己维护了一个父POM，通过import引入Spring Boot BOM。原因是我们有几个自定义的父级配置（比如统一的编译插件参数、统一的资源过滤），直接继承Spring Boot的parent会被它的插件配置限制，自定义起来稍微绕。如果你是基础项目，直接继承spring-boot-starter-parent更省事，两种方式没有绝对优劣，看团队项目复杂度。

3.4 子模块如何正确声明parent

子模块的pom.xml开头需要写：

<parent> <groupId>com.dzxt.demo</groupId> <artifactId>platform-parent</artifactId> <version>1.0.0-SNAPSHOT</version> <relativePath>../pom.xml</relativePath> </parent>

relativePath指定父POM的相对路径，默认是../pom.xml。如果父POM已经在私服仓库里，也可以把relativePath删掉，Maven会去仓库查找。但本地开发阶段，我建议保留relativePath，这样父POM和子模块在同一套工程里，改本地父POM立刻生效，不需要先install再让子模块读取。

父POM中的依赖管理细节还有一种更高阶的用法：插件管理（pluginManagement）。和dependencyManagement逻辑完全一样，只锁插件版本和配置，子模块声明相同插件时不写版本即可。比如统一maven-compiler-plugin：

<build> <pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <source>${java.version}</source> <target>${java.version}</target> <encoding>UTF-8</encoding> </configuration> </plugin> </plugins> </pluginManagement> </build>

这个设置能让所有模块统一编译参数，避免某个模块单独用JDK 8、其他模块用JDK 17的混乱。

4. 私服仓库：从零部署到日常使用

4.1 为什么要自建私服

公共组件管理、内部jar包分发、外网依赖加速，这三个理由几乎就是自建私服的三大支柱。没有私服时，每个开发者的本地仓库各存各的，新成员加入要把本地整个.m2仓库拷过去，哪怕是公司内部的自研组件也得从某个人的本地仓库install出来再传给下一个人。私服（通常用Nexus或Artifactory，我在这套方案里用的是Nexus）解决了三个问题：

• 统一集中存放外部依赖，不需要每个人都访问外网仓库。
• 发布内部组件，团队其他人通过私服拉取。
• 控制依赖来源，安全合规审查只需要看私服仓库里有什么。

4.2 部署基础与仓库类型

部署Nexus的过程不算复杂，在服务器上装好JDK后解压，配置端口、管理员密码，启动服务即可。关键在仓库类型的规划上。Nexus支持的仓库类型主要有四种：

• maven-central：代理中央仓库的代理仓库
• maven-releases：存放正式版本构件的宿主仓库
• maven-snapshots：存放快照版本构件的宿主仓库
• maven-public：组合仓库，把上面三种聚合起来对外统一暴露

我建议在Nexus建库时注意仓库命名清晰，然后对maven-public的组成顺序做调整。常用的方式是hosted仓库在前、proxy仓库在后。因为如果你某个内部组件的groupId和中央仓库里的完全一致，Maven会按仓库顺序逐个查，先命中私服里的内部组件，避免拉外网。

4.3 settings.xml与镜像配置

部署完私服，开发者侧只需要改本地Maven的settings.xml。最关键的配置是<mirror>，这一步几乎所有人都会遇到：

<settings> <mirrors> <mirror> <id>nexus-internal</id> <mirrorOf>*</mirrorOf> <url>http://nexus-server:8081/repository/maven-public/</url> </mirror> </mirrors> <servers> <server> <id>nexus-internal</id> <username>deploy-user</username> <password>deploy-password</password> </server> </servers> </settings>

mirrorOf通配符的含义是把所有中央仓库、自定义仓库的下载请求，统一重定向到私服的maven-public仓库。这样开发者本地根本不需要自己关心依赖从哪个源来，只要命中的坐标私服里有，Maven就能拉到。私服本身会代理中央仓库下载外部依赖，所以本地无需再单独连外网。

提示：mirrorOf 里写*表示所有仓库都走mirror。也有写法是external:*，表示只有本地没有的仓库才走私服。小团队建议直接用*，最简单，不会莫名其妙绕过私服导致依赖从别的仓库拉下来。

私服地址这里我用的是http://nexus-server:8081，实际部署时替换成你自己的服务器地址。注意Nexus的仓库路径格式是/repository/仓库名/，漏掉repository这个前缀是新手最容易配错的地方。

4.4 构件上传与版本发布策略

内部组件的发布有两种常规方式。一种是直接用Maven的deploy插件：

mvn clean deploy

deploy时会按pom中声明的distributionManagement将构件推送到私服的对应仓库。需要在pom.xml里配置：

<distributionManagement> <repository> <id>nexus-internal</id> <url>http://nexus-server:8081/repository/maven-releases/</url> </repository> <snapshotRepository> <id>nexus-internal</id> <url>http://nexus-server:8081/repository/maven-snapshots/</url> </snapshotRepository> </distributionManagement>

这里id要与settings.xml中server的id保持一致，否则认证不到。版本号带-SNAPSHOT后缀的会自动推送到snapshotRepository，不带后缀且非大写的正式版本会推送到repository。我见过有人把正式组件版本号写成1.0.0-SNAPSHOT后一直发布不上去，就是没理解快照和正式版本的分类逻辑。

版本发布策略上，我的建议是：分支开发期间内部组件一律用SNAPSHOT版本，每次deploy都能覆盖上次的同名快照；进入发版稳定阶段后，统一改正式版本号，推送到maven-releases。正式版本号一旦发布就不可覆盖，这是Nexus默认强制规则，能有效防止同一版本被反复修改带来的依赖混乱。

4.5 快照版本更新策略

快照版本的更新遵循Maven构建时的策略，默认情况下同一快照版本构件在24小时内不会重复拉取。这导致一个典型问题：我上午发布了1.0.1-SNAPSHOT，下午别人构建依赖它，但拉到的是上午的旧jar，看不到新改动。

解决方式有两种。一种是强制更新依赖快照版本：

mvn clean install -U

-U参数会让Maven强制检查所有快照版本并更新。在CI和流水线里，我通常会在关键构建步骤加上这个参数。另一种是修改settings.xml中的快照策略为always，但我不建议，会让每次构建都尝试连接私服，本地开发时反而拖慢速度。

5. 常见问题与排查技巧实录

5.1 公司内网无法下载依赖，构建一直报错

这类问题通常出在mirror配置没生效。先执行mvn help:effective-settings查看当前生效的settings内容，第一步确认mirror是否在列。如果mirror存在但构建还是无法下载，用mvn dependency:resolve -X开启调试日志，看构建过程中实际访问的仓库URL是什么。我在某公司的实践中，有次问题不是出在mirror，而是开发机的hosts文件没配置私服域名解析，导致连接超时。这种低级问题排查最花时间，建议第一步先验证网络连通性，ping一下私服地址，再用curl访问私服仓库解释连通。

5.2 私服已经上传了新构件，别人却拉不下来

分两种情况排查。如果新构件是SNAPSHOT版本，多半是快照更新策略导致，直接在目标工程执行mvn clean install -U强制刷新。如果新构件是release版本，去Nexus界面查构件列表，确认构件确实上传成功；另外确认依赖方pom.xml里声明的仓库id是否正确对应distributionManagement中的id。我实际遇到过本地deploy成功，但Nexus上显示构件存在私服仓库的maven-releases里，而依赖方走的镜像路径拼错了仓库名，导致404。

5.3 依赖冲突：两个模块引用了同一个库的不同版本

继承机制统一了内部模块间的版本，但第三方直接依赖之间还是可能冲突。比如模块A引入fastjson2 2.0.43，模块B引入fastjson2 2.0.36，最终打出来的包用哪个版本，取决于最近的依赖声明和依赖树顺序。排查手段是用依赖树分析命令：

mvn dependency:tree -Dverbose

-Dverbose会把被省略的中间依赖也展开，能看到每个版本的实际来源。定位问题后可以精准排除，比如排除不需要的transitive依赖：

<dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2</artifactId> <version>2.0.43</version> <exclusions> <exclusion> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2-extension</artifactId> </exclusion> </exclusions> </dependency>

更省事的方式是在dependencyManagement中统一指定冲突库的版本，让所有模块都显式遵循同一个版本。

5.4 私服宕机或仓库迁移

私服一旦宕机，所有构建都会挂掉。我经历过一次，解决方案是把本地仓库的缓存尽可能保留住，然后临时在settings.xml中把镜像url改回中央仓库地址，让构建直接从中央仓库拉依赖。这要求开发者的本地仓库（默认~/.m2/repository）足够完整，否则大量依赖要从外网重新下载，构建时间会非常长。给个建议：保持本地仓库定期不清理，也别随手执行mvn -U把所有缓存强制刷掉。实际维护中，本地仓库缓存是私服故障时的重要B计划。

5.5 非公网仓库无法访问中央仓库的额外问题

某次在隔离网络环境部署私服时，部署机无法访问外网中央仓库。解决方案是先在能外网的机器上把中央仓库依赖全部下载到本地，然后把这些文件上传到私服宿主仓库，或者用Nexus的upload组件接口手工上传。这个方案很蠢但有效，类似离线安装包的概念。如果团队常驻隔离网络环境，更推荐一开始就在私服上配置好proxy仓库，并把需要的外部依赖预先拉取进代理缓存。

6. 落地这套方案时我留下的几条经验

工程化改造这件事，表面上是改一堆pom.xml，实际是在设计团队的依赖治理规则。有几点我特别想强调：

• 父POM里的dependencyManagement是一个团队的依赖标准，要指定专人维护，不能谁都能改，否则版本混乱问题依旧存在，只是从子模块挪到了父POM。
• 私服权限要区分开发者和发布者身份。普通开发只需读权限，能拉依赖就行；deploy权限只给维护者，避免有人不小心把开发中的半成品组件推成正式版本。
• 聚合工程和继承机制单独用都能解决问题，合起来威力最大。但配合使用时，务必理解壳工程和父POM角色分离的设计，否则项目后期维护时会发现改动一环牵动全局。
• 快照和正式版本的使用要形成团队规范。开发期用快照，迭代快；上线前切正式版本，稳定可追溯。发布流水线里要有check，禁止把正式版本覆盖成不同代码。

最后再分享一个小技巧。如果需要快速定位某构件最终来自哪个仓库（私服的哪个仓库路径），可以在Nexus界面中搜索构件坐标后，查看它在仓库中的位置。点进构件详情页，能看到仓库路径，比如maven-public/com/dzxt/demo/platform-common/1.0.0-SNAPSHOT/，这时候可以反向确认私服代理路线上出了什么问题。这套方案跑下来，我最大的感受是：Maven的高级功能其实不复杂，复杂的是在团队协作里把规则定清楚并执行下去。工程化和规范化的价值，往往在踩坑之后才能切身感受到。