---

Pre

Maven - Manual Maven JAR Installation：用 mvn install:install-file 安裝本地 JAR 的實用指南

概述

在 Spring Boot 項目中，通常依賴包會從 Maven 中央倉庫或私有倉庫獲取，并由 spring-boot-maven-plugin 自動打包進最終的可執行 fat jar（BOOT-INF/lib 目錄）。
但在實際開發中，有時會遇到無法從公共或私有倉庫獲取的第三方 jar，例如廠商提供的 SDK、本地編譯生成的工具包、未開源的內部依賴等。

如果直接使用 <scope>system</scope> 引入本地 jar，雖然能在編譯時解析，但 Maven 默認不會將 system scope 依賴打入 Spring Boot 的 fat jar 中，導致部署后運行時找不到該類。

為了解決這一問題，需要在打包階段顯式將這些 jar 文件復制到 BOOT-INF/lib 目錄，確保它們隨 Spring Boot 應用一起分發與運行。

這個場景尤其適用于：

• 快速集成：臨時引入無法上傳至私服的第三方 jar。
• 離線部署：運行環境無法訪問外部倉庫。
• 封閉式交付：需要將全部依賴打包成一個獨立可運行的 jar 文件。

方案思路

1. 編譯期：使用 <scope>system</scope> 讓本地 jar 參與編譯。
2. 打包期：通過 maven-resources-plugin 在 process-resources 階段將本地 jar 文件復制到 target/classes/BOOT-INF/lib，這樣 spring-boot-maven-plugin 在 repackage 時會將其一并打入 fat jar。
3. 運行期：由于 jar 已進入 BOOT-INF/lib，Spring Boot 的類加載器會自動加載。

構建流程圖

工作機制說明

1. 資源復制階段
   maven-resources-plugin 在 process-resources 階段，將 src/main/resources/lib 中的所有 jar 文件復制到 target/classes/BOOT-INF/lib。
2. 打包階段
   spring-boot-maven-plugin 在 repackage 階段會打包所有在 BOOT-INF/lib 的 jar 到最終可執行 jar 中。
3. 運行階段
   Spring Boot 啟動時會用自帶的類加載器加載 BOOT-INF/lib 中的所有 jar，使它們在運行時可用。

---

目錄結構示例

my-project/
├── src/
│   ├── main/
│   │   ├── java/...         # 源碼
│   │   ├── resources/
│   │   │   ├── application.yml
│   │   │   └── lib/
│   │   │       └── your.jar  # 本地 jar
├── pom.xml

---

POM 配置模板

<dependency><groupId>com.xxx</groupId><artifactId>your-artifact</artifactId><version>1.0.0</version><scope>system</scope><systemPath>${project.basedir}/src/main/resources/lib/your.jar</systemPath>
</dependency><build><plugins><!-- 復制本地 jar 到 BOOT-INF/lib --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-resources-plugin</artifactId><version>3.3.0</version><executions><execution><id>copy-system-jars</id><phase>process-resources</phase><goals><goal>copy-resources</goal></goals><configuration><outputDirectory>${project.build.outputDirectory}/BOOT-INF/lib</outputDirectory><resources><resource><directory>${project.basedir}/src/main/resources/lib</directory><includes><include>*.jar</include></includes></resource></resources></configuration></execution></executions></plugin><!-- Spring Boot 打包插件 --><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><includeSystemScope>true</includeSystemScope></configuration></plugin></plugins>
</build>

---

構建與驗證

mvn clean package

驗證 jar 是否被打入：

jar tf target/my-project-0.0.1-SNAPSHOT.jar | grep BOOT-INF/lib

應能看到 your.jar 記錄。

---

注意事項

• system scope 在 Maven 官方中不推薦長期使用，不具備依賴沖突檢測功能，適合臨時方案。

• 如果 jar 需要長期維護，建議安裝到本地倉庫：

  mvn install:install-file \-Dfile=src/main/resources/lib/your.jar \-DgroupId=com.xxx \-DartifactId=your-artifact \-Dversion=1.0.0 \-Dpackaging=jar
  

• 團隊協作建議使用私服（Nexus / Artifactory）管理。

---

方案優缺點

方法	核心做法	是否自動打包進 fat jar	優點	缺點	適用場景
方法 1：安裝到本地 Maven 倉庫	mvn install:install-file 安裝到 ~/.m2/repository，pom.xml 正常依賴	? 會打包	- 符合 Maven 規范 - 支持版本管理與沖突檢測 - CI/CD 無障礙	- 初次使用需執行安裝命令 - jar 更新需重新安裝	jar 可長期使用，且團隊或構建環境可訪問本地/遠程倉庫
方法 2：上傳到私服（Nexus/Artifactory）	上傳 jar 到私服倉庫，pom.xml 正常依賴	? 會打包	- 團隊共享方便 - 支持版本管理與依賴分析 - CI/CD 最友好	- 需要搭建和維護私服 - 上傳步驟比本地倉庫多	多人協作項目，需穩定依賴和自動化構建
方法 3：直接內嵌 jar（system scope）	把 jar 放到 src/main/resources/lib 并 <scope>system</scope>	? 默認不會打包（可用 includeSystemScope=true 或 maven-resources-plugin 手動復制）	- 無需上傳倉庫 - 依賴文件隨項目走	- 不走 Maven 依賴管理 - 無版本沖突檢測 - CI/CD 需額外處理 - jar 升級需手動替換	臨時測試或快速 PoC，構建環境固定且可直接帶 jar

---

方法	是否打包進 fat jar	優點	缺點	適用場景
本方案（system + 手動復制）	?	快速接入，適合臨時調試或離線部署	維護成本高，不做依賴沖突檢測	臨時/封閉環境
本地 Maven 倉庫安裝	?	符合 Maven 規范，支持版本管理	jar 更新需重新安裝	長期使用，本地構建
上傳私服	?	團隊共享方便，CI/CD 友好	需搭建和維護私服	多人協作，長期依賴

---