企业官网建设流程全解析

我在团队里带新人时，经常看到这样的场景：项目连不上别人的模块，大家第一反应就是跑到某个子模块里敲一句mvn install，敲完发现还是不行，就又加clean，再不行就删~/.m2/repository里的目录重来一遍。至于install到底触发了哪些动作、本地仓库里的文件为什么长那样、为什么明明install了别的项目却还在用旧代码，很少有人能一口气讲清楚。

这篇文章就用我这些年实际踩坑的经验，把maven install这条命令从执行到入库整个流程拆开给你看。适合刚把 Maven 用熟但还没系统理解构建链路的开发者，也适合被“多模块依赖”反复折磨、想搞明白底层逻辑的团队新人。搞懂了它，你会发现自己对日常构建、CI 发布、本地私有依赖哪一环出了问题，心里会完全有数。

1. mvn install 在构建生命周期中的真实位置

1.1 三条生命周期，最常走的是 default

Maven 不是只有一套流程，它内部定义了 clean、default、site 三套生命周期（lifecycle）。我们平时用的mvn install，走的是 default 这条主线。

这三套各自独立，但通过命令组合可以串联执行。比如mvn clean install是先走完 clean 生命周期的clean阶段，把 target 目录清掉，再走 default 生命周期到install阶段结束。site 生命周期主要用于生成项目站点报告，日常开发用得少，但也别忘了他存在。

关键是理解 default 生命周期，它不是一个命令，而是一串按顺序排列的阶段（phase）。Maven 执行某个阶段时，它不会只跑那一小步，而是从生命周期最开头一路跑到你指定的那个阶段为止。所以你执行mvn install，不是“只执行 install 这一个动作”，而是“把 default 生命周期里所有排在 install 之前的阶段全部执行完，然后再执行 install 阶段”。

这就像一个流水线：你按下“完成”按钮，不代表只做最后一个盖章动作，而是从原材料入场开始，加工、质检、包装、入库全流程一起跑完。

1.2 从 validate 到 install：整条流水线的执行顺序

default 生命周期里的阶段有很多，完整列表长得能吓到新人，我这里挑主干讲一遍：

validate、compile、test、package、verify、install、deploy 这几个是我们肉眼最常见的。但在它们之间，还藏着十几二十个自动执行的阶段，例如 process-resources、process-classes、test-compile、prepare-package 等等。

如果展开说，mvn install实际执行的顺序大致是：

1. validate：校验项目信息是否完整，POM 配置是否合法。
2. compile：编译主代码，把src/main/java的 .class 文件生成到 target/classes。
3. test：这里又分好几步，会先编译src/test/java下的测试代码，再由 maven-surefire-plugin 去跑所有单元测试。
4. package：根据 POM 里的 packaging 类型，把项目打成 jar、war、pom 或其他格式，输出到 target 目录。
5. verify：执行集成测试等额外检查，比如用 maven-failsafe-plugin 跑集成测试。
6. install：到这一步才轮到真正的主角，把构建产物复制进本地仓库。
7. deploy：你如果执行的不是 install 而是 deploy，它会继续往远程仓库推。

这里有个很反常识的点：maven 执行mvn test时，也会执行前面的 compile 等阶段；执行mvn package时，也会先跑完所有测试。也就是说，阶段不是“你可以挑选执行的单个任务”，而是“整个阶梯上你选在哪一层停”。

新人很容易踩的第一个坑就在这里：我明明只想打个包，为什么测试跑了半天？因为它默认就会跑完 test 之前的全部阶段。理解了生命周期，你就知道这不是 Maven 在无理取闹，而是它的机制设计就是如此。

1.3 看一次 mvn install 的真实日志

与其背理论，不如直接看一次真实的执行尾部输出。当一次mvn clean install跑完后，你会看到类似下面这样的内容：

[INFO] --- maven-resources-plugin:3.2.0:resources (default-resources) @ demo --- [INFO] --- maven-compiler-plugin:3.10.1:compile (default-compile) @ demo --- [INFO] --- maven-surefire-plugin:2.22.2:test (default-test) @ demo --- [INFO] Tests run: 8, Failures: 0, Errors: 0, Skipped: 0 [INFO] [INFO] --- maven-jar-plugin:3.3.0:jar (default-jar) @ demo --- [INFO] Building jar: /Users/xxx/code/demo/target/demo-1.0.0.jar [INFO] [INFO] --- maven-install-plugin:3.0.0-M1:install (default-cli) @ demo --- [INFO] Installing /Users/xxx/code/demo/target/demo-1.0.0.jar to /Users/xxx/.m2/repository/com/example/demo/1.0.0/demo-1.0.0.jar [INFO] Installing /Users/xxx/code/demo/pom.xml to /Users/xxx/.m2/repository/com/example/demo/1.0.0/demo-1.0.0.pom

注意最后这两行，这才是install阶段真正的成果：一个是 jar 文件，一个是 pom 文件，都被复制到了~/.m2/repository下对应的目录里。看到这两行Installing ... to ...，基本可以确定这次 install 成功了。

有人被“无头构建”折腾过，遇到 Maven 卡住没输出，大概率是下载依赖网络慢；而如果最后没有出现Installing ... to ...，那就要先看看前面是不是有测试失败或编译报错中断了流水线。日志里这两行，是你判断 install 是否生效的第一依据。

2. install 阶段的幕后流程与本地仓库之间的那点事

2.1 坐标决定归宿：本地仓库目录是怎么算出来的

Maven 里每个依赖都有唯一坐标：groupId、artifactId、version，再加上 packaging 类型。这个坐标不光用来找依赖，还直接决定文件在本地仓库的物理路径。

举个例子，一个项目的坐标是：

• groupId：com.example.demo
• artifactId：hello-world
• version：0.0.1-SNAPSHOT
• packaging：jar

那么它 install 过后，本地仓库里的路径就是：

~/.m2/repository/com/example/demo/hello-world/0.0.1-SNAPSHOT/

这个路径的生成规则其实很简单：把 groupId 的每个.换成一层目录，后面依次拼上 artifactId 和 version，变成groupId路径/artifactId/version/。然后把 artifactId 和 version 拼成文件名，形成hello-world-0.0.1-SNAPSHOT.jar和hello-world-0.0.1-SNAPSHOT.pom。

很多人第一次打开~/.m2/repository会觉得目录嵌套深得离谱，其实就是这个规则导致的。你看到一个 jar 的完整路径时，基本能倒推出它的坐标，反过来也成立。

记住这个映射关系特别实用。比如你怀疑某个依赖本地没装好，可以直接跑到对应目录看一眼文件到底在不在、文件大小是不是 0 字节、pom 有没有损坏。

2.2 maven-install-plugin 在 POM 里看不到，却一直在干活

实际执行 install 阶段的是 maven-install-plugin 的 install 目标。你大概率不会在自己的 pom 里显式声明这个插件，因为 Maven 在超级 POM（每个项目都隐式继承的父 POM）中已经帮你把插件和目标绑定到了相应阶段。

那么 install 目标到底做了哪些事？我把它拆开看：

第一，它会把项目的主构建产物复制到本地仓库。对普通 jar 项目来说，就是把你package阶段打出来的 jar 复制过去。如果你的 packaging 是 war，就把 war 复制过去；如果 packaging 是 pom，比如父工程模块，那它只复制 pom 文件，不会硬找一个 jar 去复制。

第二，复制的同时会把 POM 文件一起放进去。这一点常常被忽略，其实其他项目依赖你的模块时，不仅需要 jar 里的类，还需要读取 POM 里声明的传递依赖。所以本地仓库里那一个.pom文件同样非常重要，缺了它，下游项目解析你的依赖时会直接报错。

第三，它会对快照版本额外做处理。如果 version 是0.0.1-SNAPSHOT，install 插件除了复制 jar 和 pom，还会维护该版本目录下的maven-metadata-local.xml。这个文件记录的是本地这个快照的时间戳信息，虽然没有远程仓库那么复杂，但在依赖解析判断“这个快照是不是最新的”时它会起作用。

第四，如果你的项目配置了生成 sources 包或 javadoc 包，并且这些附属构件已经在构建过程中生成，install 插件会把它们作为附加构件一并复制到本地仓库。不带 classifier 的主 jar 会被下游默认依赖，带sources或javadocclassifier 的附属 jar 会在 IDE 里自动关联，方便看源码。

最后，install 还会维护一个叫_remote.repositories的文件，用来标记每个构件是从哪个远程仓库下载的，还是本地安装的。这个文件平时没人注意，但偶尔会成为疑难杂症的源头。后文排障部分我会专门讲。

2.3 package、install、deploy：三者就像打包、入库、上架

很多初学者搞不清这三个词的区别，我用仓库的类比来解释：

• mvn package：把货物打包好，放在“工位旁边的暂存区”（target 目录）。这一步不进入本地仓库，也不影响任何其他项目。
• mvn install：把打包好的货物搬到“自己家里的仓库”（本地仓库 ~/.m2/repository），以后你自己家其他的项目要用，可以随时取。
• mvn deploy：把货物上架到“对外营业的总仓库”（远程私有仓库/中央仓库），其他同事或 CI 服务器才能从这里拉取。

所以三者的核心差别就在“产物最终到了哪里”。如果你的项目只是自己本地跑，mvn install就够了；如果你希望团队里其他人也能用这个公共模块，就必须mvn deploy到远程仓库。

这里有个容易忽略的细节：执行mvn deploy时，因为生命周期是顺序执行的，它会先走到 install 阶段，把构件安装到本地仓库，然后才会执行 deploy 阶段。所以很多人以为deploy只会上传远程仓库，实际上它也会先改一遍本地仓库。如果你希望跳过本地的安装动作，早期的做法是给 maven-install-plugin 配一个 skip 参数，不过日常我们很少这么干。

还有一点要注意：本地仓库优先于远程仓库。哪怕你已经成功 deploy 到了远程服务器，只要本机~/.m2/repository里还留着旧版本的 jar，你本地构建时默认还是会用旧 jar。这解释了为什么很多人抱怨“部署了新版本，本地跑起来还是旧行为”——检查自己的本地仓库，往往比检查远端更快找到问题根源。

3. 多模块项目里 install 的实操套路

3.1 为什么子模块之间“连不上”时敲 install 最管用

多模块项目是 Maven 使用频率最高的场景。一个典型的微服务或分层工程，通常有一个父 POM 和一些子模块，比如：

my-project/ ├── pom.xml (packaging=pom) ├── common/ ├── service-api/ └── web/

假设service-api依赖common，web又依赖service-api。你在根目录直接跑mvn clean install时，Maven 会构建一个 reactor，把所有模块都纳入同一个构建组，然后根据模块间的依赖关系自动排序，保证被依赖的模块先构建。

这里有一个关键知识：在同一个 reactor 中，如果web依赖service-api，Maven 访问的其实未必是本地仓库里的 jar，而可能是service-api模块的target/classes目录。也就是说，只要它们是同一个 reactor 一起构建的，子模块之间可以暂时不依赖本地仓库。

既然如此，那为什么很多团队还是建议“多模块项目先 install 公共模块”？因为一旦你脱离 reactor，单独构建其中某个模块，比如你在web目录里直接跑mvn spring-boot:run或mvn package，Maven 就不再认识common和service-api的源码，只能从本地仓库找它们的 jar。如果这些模块之前没有 install 到本地仓库，或者安装的还是旧版本，你立刻就会遇到“类找不到”或“方法不存在”的报错。

所以多模块场景下的最优习惯是：公共模块有改动后，先在根目录或公共模块目录执行一次mvn clean install，把最新产物同步到本地仓库，再去跑依赖它的业务模块。

3.2 官方组合拳：-pl 与 -am

有时候全量构建太重，尤其子模块很多、测试又慢的时候，你只改了底层的一个公共模块，结果要等整个工程全量打包一遍。这时候 Maven 提供了一组特别好用的参数。

先看一个小型父工程结构：

parent ├── pom.xml ├── base-common └── user-service

如果你只改了base-common，只想重新构建并装好它，运行：

mvn clean install -pl base-common

-pl是--projects的缩写，后面可以跟模块名，也可以跟相对路径。这样 Maven 只会去构建列出的模块，而不是把所有模块都跑一遍。

但实际工作中有个更常见的需求：项目里存在多级依赖，你想构建user-service，但又怕它依赖的base-common还没更新，于是希望把依赖它的模块一起带上。这时候要用-am，也就是--also-make：

mvn clean install -pl user-service -am

上面这行的意思是：构建user-service，同时把它依赖到的其他模块（比如base-common）也一起构建并 install。

组合起来最常用的命令长这样：

mvn clean install -pl user-service -am -DskipTests

这个命令在我的日常开发里使用频率极高。

在本地开发一个相对独立的业务服务时，根本不需要每次全量 build 几十个模块，找到你本次依赖的最上游模块，用-pl加上-am控制范围，既能保证产物最新，又能节约大量时间。

3.3 跳过测试的各种姿势与代价

install默认是会跑测试的，因为在生命周期里test阶段排在install前面。如果一个模块的单元测试写得比较慢，或者某些测试依赖外部环境，构建很容易卡在这里。

两条主流跳过测试的参数经常被混用，实际上差别不小：

mvn install -DskipTests

表示“测试代码照常编译，只是不执行”。好处是编译环节仍然会暴露测试代码里的语法问题，不会让坏代码一路混过去。这对保证代码质量更友好。

mvn install -Dmaven.test.skip=true

表示“测试代码直接不编译，也不执行”。这个参数会让 maven-compiler-plugin 连testCompile都跳过，速度最快，但如果测试代码里有编译错误，你完全发现不了，等到 CI 或别人跑测试时才会爆出问题。

我个人的习惯是：本地做快速验证时用-DskipTests，因为它保留了编译检查；只有在某些测试依赖外部中间件、本地根本没有环境时才用-Dmaven.test.skip=true。如果两边参数被混用弄乱了，可以在命令行加-X查看实际执行了哪些插件目标，排查起来看得一清二楚。

4. 那些 install 之后依然找不到依赖的破事

4.1 老毛病：改了代码却忘了重新 install

这是多模块项目里出现频率最高的问题，没有之一。你改了一个公共模块，比如base-common里的一个工具类方法，然后在user-service里调用新方法，编译时却报错找不到方法。第一反应往往是“代码是不是没保存”“IDE 是不是缓存坏了”，但真正的答案通常是：本地仓库里那个base-common-1.0.0-SNAPSHOT.jar还是旧的，源代码没重新 install 过。

为什么会这样？前面说过，单独构建下游项目时，Maven 依赖解析是先找本地仓库，找不到才去远程仓库。它会优先使用本地仓库里的同名同版本 jar，而这个 jar 不会因为你改了源码就自动更新，必须重新执行mvn install才会被新的 jar 替换。

解决办法看起来简单，但实际工程里有个很容易踩到的小分支：当你改了公共模块代码后，很多人在 IDEA 里只点模块目录的 install，没跑到根目录全量构建。如果这个模块本身还依赖了其他兄弟模块的未发布改动，只 install 单模块依然会失败或装了残缺版本。

我的经验是，在父工程目录统一执行：

mvn clean install -pl base-common -am

把该模块以及它依赖的兄弟模块一起装进本地仓库，然后再去下游模块构建。

4.2 依赖为什么不走中央仓库，偏偏先看本地

另一个困扰大家的问题是：本地仓库里的 SNAPSHOT 依赖没更新，但明明远程（比如公司私服）已经有新版本了，为什么本地项目拉不到？

这背后是 Maven 的依赖解析顺序：本地仓库优先。Maven 在解析坐标时，会首先看本地仓库有没有这个 groupId、artifactId、version 对应的目录和文件；如果存在，通常就直接用了，只有当本地不存在，或者本地遇到了构建失败、文件损坏需要重试时，才会去远程仓库下载。对 SNAPSHOT 版本来说，Maven 可以配置更新策略去检查远程仓库的快照有没有更新，但默认更新频率很低，不是每次都去找远程比对。

所以当你要强制拉取远程仓库中一个比较新的 SNAPSHOT 版本时，最常见的命令是加-U参数强制更新：

mvn clean install -U

-U会强制 Maven 检查所有 SNAPSHOT 依赖在远程仓库是否有更新，把本地可以更新的快照强制覆盖一遍。如果你怀疑某个快照依赖还停留在老版本，用这个参数基本能解决。

如果你不想每次输入这个参数，也可以在 pom 或 settings 里给仓库配updatePolicy，例如always，但那会让每次构建都去远程仓库检查一遍快照，速度会明显变慢，一般不建议。做开发时，遇到快照问题时临时用-U才是高效的方案。

4.3 手动把三方 jar 塞进本地仓库：install-file

除了自己项目的模块，开发中还经常遇到一种情况：需要用到某个第三方 jar，但这个 jar 不在 Maven 中央仓库和公司私服里，只有供应商发来的一个文件。你不能把它直接扔进项目 lib 目录就完事，更规范的做法是把 jar 手工安装到本地仓库，让 Maven 像管理普通依赖一样管理它。

它的标准命令是：

mvn install:install-file \ -Dfile=/path/to/your-custom.jar \ -DgroupId=com.example \ -DartifactId=your-custom \ -Dversion=1.0.0 \ -Dpackaging=jar

执行成功后，Maven 会把 jar 复制到~/.m2/repository/com/example/your-custom/1.0.0/your-custom-1.0.0.jar，同时生成对应的 pom 文件。这样你在其他项目的 pom 里就能像普通依赖一样写坐标引用了。

这里有几个实操细节要特别注意：

如果该 jar 还依赖了别的第三方库，手工 install-file 不会自动把依赖关系写进 pom，除非你额外用-DpomFile=xxx.pom指定一个 pom 文件，否则下游项目引用后可能会因为缺传递依赖而运行时报ClassNotFoundException。最好在供应商资料里找一找有没有对应的 pom，没有的话只能自己写一个最小的 pom 传进去。

另外，install-file 默认会覆盖本地仓库里同坐标的文件。如果你需要插入多个不同版本，要确保-Dversion也对应修改，否则会把旧版本覆盖掉，导致其他项目引用旧版本时也被悄悄换了包。

4.4 常见问题速查表

上面讲了很多场景，我把这些年遇到的和 install 相关的典型问题整理成一个速查表，方便你定位崩溃现场：

最后再分享一个和_remote.repositories相关的冷门坑。如果你把某个项目从一个旧机器拷贝到新机器，或者切换了仓库镜像源，构建时偶尔会出现“本地明明有 jar，依赖却下载失败”的奇怪现象，这经常是本地仓库里_remote.repositories记录的仓库 id 和当前配置不匹配导致的。遇到这种情况，先把对应依赖目录下的_remote.repositories删掉，再重新执行mvn install或mvn dependency:resolve，大多数时候就能恢复。这个文件看着不起眼，但它记录着依赖来源，有时候却会成为本地仓库里最隐蔽的一根刺。

我自己的习惯是，对核心公共模块的改动，永远先跑一次干净的mvn clean install，并盯着日志确认出现那两行Installing ... to ...，再切换到下游模块继续开发。Maven 的本地仓库就像是所有本地工程共同仰仗的“后厨”，你不把最新菜品送进后厨，前厅的顾客能点的永远只有旧菜单。把这条思路想通，很多 install 相关的疑难杂症就都不难定位了。