Maven 内置预定义变量以及定义变量

预定义变量以及定义变量

一、Maven 内置预定义变量

这类变量是 Maven 自带的核心变量，全局生效，无需任何配置即可直接引用，也是最常用的变量类型。

变量名	含义	典型使用场景
`${project.version}`	当前项目（模块）的版本号（子模块默认继承父模块）	依赖管理中统一版本、打包命名
`${project.groupId}`	当前项目的 GroupId（子模块默认继承父模块）	依赖坐标、自定义插件配置
`${project.artifactId}`	当前项目的 ArtifactId	打包输出文件名、依赖坐标
`${project.name}`	当前项目的名称（对应 POM 中 `<name>` 标签）	日志输出、报告生成
`${project.basedir}`	当前项目的根目录（本地绝对路径）	配置文件路径、资源拷贝路径
`${project.build.directory}`	项目构建输出目录（默认 `target`）	插件输出路径、自定义打包路径
`${project.build.sourceDirectory}`	主源码目录（默认 `src/main/java`）	源码编译配置
`${settings.localRepository}`	本地 Maven 仓库路径（默认 `~/.m2/repository`）	依赖下载路径、仓库配置
`${maven.version}`	当前使用的 Maven 版本	插件兼容性判断
`${java.version}`	当前使用的 JDK 版本（对应 POM 中 `<maven.compiler.source>`）	编译插件配置

示例用法：

<!-- 1. 复用当前项目的坐标 -->
<dependency>
    <groupId>${project.groupId}</groupId>
    <artifactId>${project.artifactId}-common</artifactId>
    <version>${project.version}</version>
</dependency>

<!-- 2. 指定构建输出路径 -->
<build>
    <directory>${project.basedir}/build</directory> <!-- 替换默认的 target -->
</build>

二、POM 中自定义变量

如果内置变量不够用，可以在 POM 的 <properties> 标签中自定义变量，适合统一管理重复值（如依赖版本、配置参数）。

1. 定义方式

父模块定义，子模块继承。

<!-- 父模块 pom.xml -->
<properties>
    <!-- 自定义版本变量 -->
    <spring.boot.version>2.7.15</spring.boot.version>
    <mysql.version>8.0.33</mysql.version>
    <!-- 自定义路径变量 -->
    <custom.resource.dir>${project.basedir}/src/main/resources/custom</custom.resource.dir>
    <!-- 自定义模块前缀 -->
    <rootArtifactId>demo-project</rootArtifactId>
</properties>

2. 使用方式

父/子模块均可直接引用。

<!-- 子模块 pom.xml -->
<dependencies>
    <!-- 引用自定义版本变量 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring.boot.version}</version>
    </dependency>
</dependencies>

<!-- 引用自定义模块前缀 -->
<artifactId>${rootArtifactId}-controller</artifactId>

三、命令行传入的变量

临时变量，仅本次构建生效。

通过 mvn 命令行参数 -D 传入的变量，适合临时覆盖配置、模板生成传参。

1. 传入方式

# 示例1：构建时指定版本
mvn clean install -Dproject.version=2.0.0

# 示例2：模板生成时传参
mvn archetype:generate -DrootArtifactId=my-project -Dversion=1.0.0

2. 使用方式

直接在 POM 中引用：${rootArtifactId}、${version}；
模板文件中要求必须传入：<requiredProperty key="rootArtifactId"/>（模板引擎语法）。

四、Profile 中的变量（按环境切换）

在 <profiles> 中定义环境相关的变量，可通过命令行激活不同 Profile 切换变量值（如开发/测试/生产环境）。

1. 定义方式

<profiles>
    <!-- 开发环境 -->
    <profile>
        <id>dev</id>
        <properties>
            <env>dev</env>
            <db.url>jdbc:mysql://localhost:3306/dev_db</db.url>
        </properties>
    </profile>
    <!-- 生产环境 -->
    <profile>
        <id>prod</id>
        <properties>
            <env>prod</env>
            <db.url>jdbc:mysql://prod-db:3306/prod_db</db.url>
        </properties>
    </profile>
</profiles>

2. 激活并使用

# 激活 prod 环境
mvn clean package -Pprod

# POM 中引用
<configuration>
    <url>${db.url}</url>
</configuration>

五、模板引擎变量

仅模板文件生效，如 Archetype

这类变量是代码生成模板（Velocity/Freemarker）的专属变量，仅在模板文件（.vm/.ftl/archetype-metadata.xml）中生效，和 Maven 变量是不同层面的东西。

变量相关语法	含义
`<requiredProperty key="xxx"/>`	要求生成项目时必须传入 `xxx` 变量（如 `-Dxxx=value`），否则报错
`${xxx}`	模板中引用传入的变量（生成时替换为实际值）
`__rootArtifactId__`	部分模板的占位符语法（等价于 `${rootArtifactId}`）

示例（archetype-metadata.xml）：

<requiredProperties>
    <requiredProperty key="rootArtifactId"/> <!-- 必须传 rootArtifactId 参数 -->
    <requiredProperty key="version" defaultValue="1.0.0"/> <!-- 可选，默认值 1.0.0 -->
</requiredProperties>

<modules>
    <module id="${rootArtifactId}-common" dir="__rootArtifactId__-common"/>
</modules>

六、变量优先级

当多个地方定义了同名变量时，Maven 按以下优先级取值（从高到低）：
1. 命令行传入的变量（-Dxxx=value）；
2. Profile 中激活的变量；
3. POM 中 <properties> 自定义的变量；
4. 父模块继承的变量；
5. Maven 内置的预定义变量。

总结

常用核心变量：${project.version}/${project.groupId}/${project.artifactId} 是 Maven 内置的，无需定义直接用，适合多模块统一坐标；
自定义变量：在 <properties> 中定义（如 ${rootArtifactId}/${spring.boot.version}），适合统一管理重复配置；
临时变量：命令行 -D 传入（如 -Dversion=1.0.0），适合模板生成、临时覆盖配置；
环境变量：Profile 中定义，适合按环境切换配置；
模板变量：<requiredProperty>/${xxx} 是模板引擎语法，仅在生成项目时生效，和 Maven 原生变量要区分开。