IntelliJ IDEA 引入本地 JAR 並打包 WAR 完整指南

場景說明

專案依賴私有/未發布至 Maven 倉庫的 JAR 檔，需手動引入並確保打包 WAR 時包含這些依賴。

步驟一：在 IDEA 中引入本地函式庫

1. 開啟 File → Project Structure（Ctrl+Alt+Shift+S）。
2. 選擇左側 Libraries，點擊 + → Java，選擇本地 JAR 目錄或單一 JAR 檔。
3. 命名函式庫（如 local-libs），確認加入模組。

4. 切換到 Modules → Dependencies，點擊 + → Library，選擇剛建立的 local-libs。
5. 將 Scope 設為 Compile（預設），確保編譯與執行時可用。

步驟二：Maven 打包 WAR 時包含本地 JAR

IDEA 的 Library 設定僅影響 IDE 編譯與執行，Maven 打包需額外配置 maven-war-plugin。

方案：將本地 JAR 放入專案 lib/ 目錄，打包時複製至 WEB-INF/lib

<build>
    <finalName>${project.artifactId}</finalName>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>3.3.2</version>
            <configuration>
                <failOnMissingWebXml>false</failOnMissingWebXml>
                <warName>${project.artifactId}</warName>
                <webResources>
                    <resource>
                        <directory>${project.basedir}/lib</directory>
                        <targetPath>WEB-INF/lib</targetPath>
                        <includes>
                            <include>**/*.jar</include>
                        </includes>
                    </resource>
                </webResources>
            </configuration>
        </plugin>
    </plugins>
</build>

目錄結構範例

project-root/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   ├── resources/
│   │   └── webapp/
│   │       └── WEB-INF/
│   │           └── web.xml
│   └── test/
└── lib/                    # 本地 JAR 放置處
    ├── proprietary-api.jar
    └── legacy-utils.jar

進階方案：安裝至本地/私有 Maven 倉庫（推薦）

手動安裝單一 JAR：

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

安裝後在 pom.xml 正常引用：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>proprietary-api</artifactId>
    <version>1.0.0</version>
</dependency>

優點：符合 Maven 規範、支援傳遞性依賴、CI/CD 友善、多人協作無需共享 lib/ 目錄。

驗證 WAR 包內容

# 解壓檢查
jar -tf target/your-app.war | grep WEB-INF/lib

# 或使用 unzip
unzip -l target/your-app.war | grep WEB-INF/lib

確認輸出包含：

WEB-INF/lib/proprietary-api-1.0.0.jar
WEB-INF/lib/legacy-utils.jar
WEB-INF/lib/... (其他 Maven 依賴)

常見坑點避雷

最佳實踐建議

1. 優先使用私有 Maven 倉庫（Nexus、Artifactory、GitHub Packages），避免本地 JAR 管理混亂。
2. 若必須用本地 JAR，統一放置於 lib/ 目錄並納入版控（或文件化安裝步驟）。
3. 配置 maven-war-plugin 時指定 failOnMissingWebXml=false（Servlet 3.0+ 可無 web.xml）。
4. CI/CD 流水線中執行 mvn clean package 驗證打包結果。