Ubuntu 22.04（WSL2）上安装 Maven 3.8.9

发布于：2025-06-24 ⋅ 阅读:(16) ⋅ 点赞:(0)

引言

Apache Maven 是一个广泛使用的项目管理工具，尤其在 Java 项目中用于构建和依赖管理。本文将详细介绍如何在 Ubuntu 22.04（运行于 WSL2）上安装 Maven 3.8.9（3.8 系列的最后一个版本），并深入讲解 Maven 的全局 settings.xml 配置文件的结构和使用。

前提条件

  • 已安装 WSL2 并运行 Ubuntu 22.04。
  • 已安装 JDK（Java Development Kit） 8 或更高版本（推荐 JDK 11 或 17）。注意：仅 JRE（Java Runtime Environment）不足以支持 Maven，因为 Maven 需要编译器（javac）等开发工具。

一、安装步骤

1. 检查 Java 环境

Maven 需要 JDK 环境（而非仅 JRE），确保已安装 JDK。运行以下命令检查 Java 和编译器版本：

java -version
javac -version

输出类似以下内容表示已安装 JDK（版本需为 8 或更高）：

openjdk version "11.0.11" 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing)

javac 11.0.11

如果 javac -version 提示命令未找到，则说明只安装了 JRE，需要安装 JDK。使用以下命令安装 OpenJDK 11：

sudo apt update
sudo apt install openjdk-11-jdk

2. 下载 Maven 3.8.9

访问 Apache Maven 官网或使用 wget 下载 Maven 3.8.9 的二进制文件。运行以下命令：

wget https://archive.apache.org/dist/maven/maven-3/3.8.9/binaries/apache-maven-3.8.9-bin.tar.gz

注意：请确认链接是否为最新版本，可访问 Maven 下载页面 获取最新版本链接。

3. 解压 Maven 文件

将下载的压缩包解压到 /opt 目录（推荐用于系统工具安装）：

sudo tar -xvzf apache-maven-3.8.9-bin.tar.gz -C /opt

解压后，Maven 文件夹将位于 /opt/apache-maven-3.8.9。

4. 配置环境变量

为了在终端中直接使用 mvn 命令，需要配置 Maven 的环境变量。编辑 ~/.bashrc 文件：

nano ~/.bashrc

在文件末尾添加以下内容：

export M2_HOME=/opt/apache-maven-3.8.9
export PATH=$M2_HOME/bin:$PATH

保存并退出后，运行以下命令使环境变量生效：

source ~/.bashrc

5. 验证 Maven 安装

检查 Maven 是否正确安装并配置，运行以下命令：

mvn -version

预期输出类似：

Apache Maven 3.8.9 (356d02a104aec4a9f3a759e4bb8124f1f5b8c7e0)
Maven home: /opt/apache-maven-3.8.9
Java version: 11.0.11, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "5.15.0-73-generic", arch: "amd64", family: "unix"

二、配置 Maven 的 settings.xml

Maven 的配置文件 settings.xml 用于自定义 Maven 的行为，例如设置本地仓库路径、配置镜像源、代理设置等。Maven 会读取以下位置的 settings.xml 文件（按优先级顺序）：

  1. 用户级配置文件：~/.m2/settings.xml（需要手动创建，默认不存在）。
  2. 全局配置文件：Maven 安装目录下的 /opt/apache-maven-3.8.9/conf/settings.xml（默认存在）。

Maven 安装时，/opt/apache-maven-3.8.9/conf/settings.xml 文件总是存在的，包含默认配置（稍后详细介绍）。推荐优先使用全局配置文件，因为：

  • 统一性：便于在多用户环境（如服务器或团队开发）中共享配置。
  • 可维护性：避免因用户目录迁移或重置导致配置丢失。
  • 版本控制：全局配置文件可以纳入版本控制，便于管理。

1. 默认 settings.xml 内容

Maven 3.8.9 的默认全局 settings.xml（位于 /opt/apache-maven-3.8.9/conf/settings.xml）包含以下主要结构（已精简注释）：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <!-- 本地仓库路径，默认：${user.home}/.m2/repository -->
  <localRepository>/path/to/local/repo</localRepository>

  <!-- 是否启用交互模式，默认：true -->
  <interactiveMode>true</interactiveMode>

  <!-- 是否离线模式，默认：false -->
  <offline>false</offline>

  <!-- 插件组，用于解析插件前缀 -->
  <pluginGroups>
    <!-- 示例：<pluginGroup>com.your.plugins</pluginGroup> -->
  </pluginGroups>

  <!-- 代理设置 -->
  <proxies>
    <!-- 示例代理配置
    <proxy>
      <id>optional</id>
      <active>true</active>
      <protocol>http</protocol>
      <username>proxyuser</username>
      <password>proxypass</password>
      <host>proxy.host.net</host>
      <port>80</port>
      <nonProxyHosts>local.net|some.host.com</nonProxyHosts>
    </proxy>
    -->
  </proxies>

  <!-- 服务器认证设置 -->
  <servers>
    <!-- 示例服务器配置
    <server>
      <id>deploymentRepo</id>
      <username>repouser</username>
      <password>repopwd</password>
    </server>
    -->
  </servers>

  <!-- 镜像源设置 -->
  <mirrors>
    <mirror>
      <id>maven-default-http-blocker</id>
      <mirrorOf>external:http:*</mirrorOf>
      <name>Pseudo repository to mirror external repositories initially using HTTP.</name>
      <url>http://0.0.0.0/</url>
      <blocked>true</blocked>
    </mirror>
  </mirrors>

  <!-- 构建配置文件 -->
  <profiles>
    <!-- 示例：基于 JDK 版本激活的 profile
    <profile>
      <id>jdk-1.4</id>
      <activation>
        <jdk>1.4</jdk>
      </activation>
      <repositories>
        <repository>
          <id>jdk14</id>
          <name>Repository for JDK 1.4 builds</name>
          <url>http://www.myhost.com/maven/jdk14</url>
          <layout>default</layout>
          <snapshotPolicy>always</snapshotPolicy>
        </repository>
      </repositories>
    </profile>
    -->
  </profiles>

  <!-- 激活的 profile 列表 -->
  <activeProfiles>
    <!-- 示例：<activeProfile>alwaysActiveProfile</activeProfile> -->
  </activeProfiles>
</settings>
关键配置项说明
  • <localRepository>:
    • 作用：指定本地仓库路径，存储下载的依赖库和插件。
    • 默认值：${user.home}/.m2/repository（即 ~/.m2/repository）。
    • 推荐配置：自定义路径以便于管理或适配存储需求。例如，设置为 /opt/maven-repository。
    • 修改方式：取消注释 <localRepository> 标签并设置路径，如 <localRepository>/opt/maven-repository</localRepository>。
  • <interactiveMode>:
    • 作用：控制 Maven 是否在需要用户输入时提示。设为 false 时，Maven 使用默认值。
    • 默认值：true。
    • 建议：通常无需修改，除非需要自动化构建。
  • <offline>:
    • 作用：启用离线模式，禁止 Maven 联网下载依赖。
    • 默认值：false。
    • 建议：仅在无网络环境或测试时设为 true。
  • <pluginGroups>:
    • 作用：指定额外的插件组 ID，用于解析插件前缀（如 mvn prefix:goal）。
    • 默认值：包含 org.apache.maven.plugins 和 org.codehaus.mojo。
    • 建议：仅在需要自定义插件组时添加。
  • <proxies>:
    • 作用：配置网络代理，用于通过代理访问远程仓库。
    • 默认值：无代理。
    • 建议：如果需要通过代理访问网络，取消注释并配置代理信息。
  • <servers>:
    • 作用：配置服务器的认证信息（如用户名、密码或密钥）。
    • 默认值：无。
    • 建议：在需要访问私有仓库时配置。
  • <mirrors>:
    • 作用：配置镜像，用于替代默认的远程仓库地址以加速或重定向请求。
    • 默认配置：包含 maven-default-http-blocker。
    • 建议：添加国内镜像（例如阿里云`），以加速依赖下载。
  • <profiles>:
    • 作用：定义构建配置文件，可以基于条件（例如 JDK 版本、系统属性）激活，修改仓库、插件或其他属性。
    • 建议：根据项目需求添加 profile，例如为不同的环境配置不同的存储库。
  • <activeProfiles>:
    • 作用：指定默认激活的配置文件。
    • 默认值：无。
    • 建议：在需要配置时始终启用某些配置文件。

2. 配置本地仓库路径

Maven 默认将本地仓库存储在 ~/.m2/repository。为了便于管理和适应存储需求，推荐自定义本地仓库路径。编辑全局 settings.xml：

sudo nano /opt/apache-maven-3.8.9/conf/settings.xml

修改 <localRepository> 标签，例如：

<localRepository>/opt/maven-repository</localRepository>

创建该目录并确保有写入权限：

sudo mkdir -p /opt/maven-repository
sudo chown -R $USER:$USER /opt/maven-repository

说明：自定义本地仓库路径便于在多用户环境中共享仓库或将仓库存储在更大容量的磁盘分区上。

3. 配置镜像源

Maven 默认从中央仓库 (https://repo.maven.apache.org/) 下载依赖，速度可能会很慢。配置国内镜像（如阿里云）可以显著提高下载速度。编辑/opt/apache-maven-3.8.9/conf/settings.xml，在 <mirrors> 标签中添加：

<mirror>
    <id>aliyunmaven</id>
    <mirrorOf>central</mirrorOf>
    <name>aliyun maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>
  • <id>：镜像的唯一标识。
  • <mirrorOf>：指定镜像替代的仓库，central 表示替代 Maven 中央仓库。
  • <name>：镜像的描述名称。
  • <url>：镜像仓库的 HTTPS 地址。
关于 maven-default-http-blocker 镜像

默认的 settings.xml 包含以下镜像配置：

<mirror>
    <id>maven-default-http-blocker</id>
    <mirrorOf>external:http:*</mirrorOf>
    <name>Pseudo repository to mirror external repository initially using HTTP.</name>
    <url>http://0.0.0.0/</url>
    <blocked>true</blocked>
</mirror>

  • 作用：此配置是 Maven 3.8.1 及以上版本引入的安全措施，用于阻止通过不安全的 HTTP 协议访问外部仓库。

  • 细节

    ：

    • <mirrorOf>external:http:\*</mirrorOf>：拦截所有使用 HTTP 协议的外部仓库请求（external 表示非本地仓库）。
    • <url>：无效地址，确保拦截的请求不会被重新定向。
    • <blocked>：明确阻止这些请求。

  • 目的：HTTP 协议没有加密，存在安全风险（如中间人攻击）。此配置强制使用 HTTPS 协议的仓库以提高安全性。

  • 是否需要修改：

    • 推荐保留：此配置增强了安全性，尤其是在使用公共镜像（如阿里云，均为 HTTPS）时。
    • 修改场景：仅当您必须访问某个仅支持 HTTP 的仓库（不推荐）时，可以将 <block> 设置为 false 或删除此镜像配置。但更推荐的是联系仓库维护者切换到 HTTPS，或使用其他支持 HTTPS 的镜像。
    • 注意：如果保留此配置，请确保所有镜像都使用 HTTPS 地址。

4. 优先使用全局 settings.xml

Maven 默认提供的全局 settings.xml（/opt/apache-maven-3.8.9/conf/settings.xml）总是存在，推荐优先使用，因为：

  • 统一性：便于在多用户环境（如服务器或团队开发）中共享配置。
  • 可维护性：避免因用户目录迁移或重置导致配置丢失。
  • 版本控制：全局配置文件可以纳入版本控制，便于管理。

如果需要用户级配置，可复制全局 settings.xml 到 ~/.m2/settings.xml：

mkdir -p ~/.m2
cp /opt/apache-maven-3.8.9/conf/settings.xml ~/.m2/settings.xml

然后根据需要编辑 ~/.m2/settings.xml。用户级配置会覆盖全局配置。

5. 示例 settings.xml 配置

以下是一个推荐的全局 settings.xml 配置，包含自定义本地仓库和阿里云镜像：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <localRepository>/opt/maven-repository</localRepository>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>aliyun maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
    <mirror>
      <id>maven-default-http-blocker</id>
      <mirrorOf>external:http:*</mirrorOf>
      <name>Pseudo repository to mirror external repositories initially using HTTP.</name>
      <url>http://0.0.0.0/</url>
      <blocked>true</blocked>
    </mirror>
  </mirrors>
</settings>

保存后，Maven 将使用 /opt/maven-repository 作为本地仓库，并通过阿里云镜像下载依赖，同时保留 HTTP 阻塞的安全措施。

常见问题

  • 运行 mvn -version 提示命令未找到。

    • 解决：检查 ~/.bashrc 中的环境变量配置，确认 M2_HOME 和 PATH 设置无误，并运行 source ~/.bashrc。

  • 下载依赖时速度慢或网络错误。

    • 解决：确保已配置 HTTPS 镜像源（如阿里云），并检查 maven-default-http-blocker 是否阻止了 HTTP 仓库。如果遇到非标准配置（如 external:dummy:*），考虑替换为标准 HTTP 阻塞器。

  • 本地仓库路径未生效。

    • 解决：检查 settings.xml 中的 <localRepository>，确保路径正确且用户有写入权限。

  • Maven 未读取全局配置文件。

    • 解决：确保全局 settings.xml 路径正确（/opt/apache-maven-3.8.9/conf/settings.xml），或通过 mvn --global-settings /opt/apache-maven-3.8.9/conf/settings.xml 显式指定。

  • 提示缺少 javac 或编译错误。

    • 解决：确认已安装 JDK 而非仅 JRE，使用 javac -version 检查。如果缺少 JDK，安装 OpenJDK（如 sudo apt install openjdk-11-jdk）。

  • HTTP 仓库无法访问。

    • 解决：检查 <mirrors> 中的 maven-default-http-blocker 配置，确保所有仓库使用 HTTPS，或临时将 <blocked> 设为 false（不推荐）。

总结

通过以上步骤，您已在 Ubuntu 22.04（WSL2）上成功安装并配置了 Maven 3.8.9，并详细配置了全局 settings.xml，包括本地仓库路径、阿里云镜像源和 HTTPS 安全措施。确保安装了 JDK（而非仅 JRE）以支持 Maven 的编译需求。您还了解了非标准 maven-default-http-blocker 配置的潜在问题，并推荐使用标准配置以确保安全性和稳定性。现在可以高效地使用 Maven 管理 Java 项目！

希望这篇博客对您的 Maven 环境配置有所帮助！

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布