Maven 3.9+ 環境搭建與 IDEA 整合完整指南 (Windows/macOS/Linux 通用)

Maven 3.9+ 環境搭建與 IDEA 整合完整指南 (Windows/macOS/Linux 通用)

1. 前置條件：JDK 17/21 (LTS 版本推薦)

Maven 3.9+ 要求 JDK 1.7+，強烈建議使用 JDK 17 或 21 (LTS)。配置 JAVA_HOME 指向 JDK 安裝根目錄，並將 %JAVA_HOME%\bin (Win) / $JAVA_HOME/bin (Unix) 加入 PATH。驗證：java -version、javac -version。

2. 下載與安裝 Maven

• 官網：https://maven.apache.org/download.cgi
• 下載 Binary zip/tar.gz (如 apache-maven-3.9.6-bin.zip)。
• 解壓至無中文、無空格路徑，例如：
  • Windows: D:\DevTools\apache-maven-3.9.6
  • macOS/Linux: /opt/apache-maven-3.9.6 或 ~/dev/apache-maven-3.9.6

3. 配置環境變數

Windows (系統變數，需管理員)

1. 新建 MAVEN_HOME = D:\DevTools\apache-maven-3.9.6
2. 編輯 Path，新增 %MAVEN_HOME%\bin (建議置頂)。

macOS/Linux (~/.bash_profile / ~/.zshrc / /etc/profile)

export MAVEN_HOME=/opt/apache-maven-3.9.6
export PATH=$MAVEN_HOME/bin:$PATH

執行 source ~/.zshrc 生效。

4. 驗證安裝

$ mvn -v
Apache Maven 3.9.6 ...
Maven home: ...
Java version: 21.0.x, vendor: Eclipse Adoptium, runtime: ...
Default locale: zh_CN, platform encoding: UTF-8
OS name: "windows 11" / "mac os x" / "linux", version: ..., arch: "amd64" / "aarch64"

5. 核心配置優化: settings.xml (關鍵步驟)

編輯 ${MAVEN_HOME}/conf/settings.xml (全局) 或 ~/.m2/settings.xml (用戶級，推薦，優先級更高)。

5.1 配置阿里云鏡像加速 (中國大陸必備)

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>central</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
    <!-- 可追加 spring, spring-plugin, graalvm 等專用鏡像 -->
</mirrors>

5.2 配置本地倉庫路徑 (避免 C 盤/用戶目錄空間不足)

<localRepository>D:/DevTools/maven-repo</localRepository> <!-- Win -->
<!-- <localRepository>/opt/maven-repo</localRepository> --> <!-- Linux/Mac -->

5.3 配置 JDK 編譯版本 (全局生效，防止項目未指定報錯)

<profiles>
    <profile>
        <id>jdk-17</id>
        <activation>
            <activeByDefault>true</activeByDefault>
            <jdk>17</jdk>
        </activation>
        <properties>
            <maven.compiler.source>17</maven.compiler.source>
            <maven.compiler.target>17</maven.compiler.target>
            <maven.compiler.release>17</maven.compiler.release>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        </properties>
    </profile>
    <!-- 可複製配置 jdk-21 profile -->
</profiles>

6. IntelliJ IDEA 整合 Maven (圖文級)

1. Settings (Ctrl+Alt+S) → Build, Execution, Deployment → Build Tools → Maven。
2. Maven home path：選擇 Custom，瀏覽選中 Maven 解壓根目錄 (D:\DevTools\apache-maven-3.9.6)。
3. User settings file：Override，選中 ~/.m2/settings.xml (或自定義路徑)。
4. Local repository：自動讀取 settings.xml 配置，確認無誤。
5. 勾選 Import Maven projects automatically、Generate Maven run configurations for ...。
6. 點擊 Apply / OK。

驗證：打開任意 Maven 項目 (含 pom.xml)，IDEA 右側 Maven 工具窗** 可正常展開 Lifecycle/Plugins，無紅色報錯即成功。