构建与依赖 / 系统课时
配置 Manifest 与主类
配置 Manifest 与主类
要让 java -jar 直接启动 JAR,至少要让清单中的 Main-Class 指向实际存在的入口类。本篇用 Maven JAR Plugin 写入主类与版本元数据,并通过真实命令检查运行结果和 META-INF/MANIFEST.MF。
学习目标
- 能在 Maven 构建中写入
Main-Class和自定义 Manifest 元数据 - 能构建并验证可被
java -jar启动的普通 JAR - 能区分主类配置错误与依赖缺失造成的启动失败
先确认 java -jar 的三个条件
Main-Class 必须写全限定类名,例如 com.example.App,不能写 App.class。入口类还必须真的被打进 JAR,并包含 public static void main(String[] args)。
| 检查项 | 正确状态 | 常见失败 |
|---|---|---|
| Manifest | 有 Main-Class: com.example.App |
no main manifest attribute |
| 主类文件 | JAR 内存在 com/example/App.class |
找不到或无法加载主类 |
| 运行依赖 | 依赖已在可用类路径中 | NoClassDefFoundError |
普通 maven-jar-plugin 只负责打包当前项目的类和资源,不会自动把第三方依赖合并进同一个 JAR。因此“有 Main-Class”是 java -jar 的必要条件,但不等于已经得到包含全部依赖的 fat JAR。
在 POM 中写入主类和元数据
下面示例按 Maven 3.9+、JDK 17 编写,并显式固定 Maven Compiler Plugin 3.16.0 与 Maven JAR Plugin 3.5.1。manifestEntries 会把项目名和版本写入主清单区。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>manifest-demo</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.16.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<archive>
<manifest>
<mainClass>com.example.App</mainClass>
</manifest>
<manifestEntries>
<Implementation-Title>${project.artifactId}</Implementation-Title>
<Implementation-Version>${project.version}</Implementation-Version>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>
</project>再创建 src/main/java/com/example/App.java:
package com.example;
public class App {
public static void main(String[] args) {
// 保持入口无外部依赖,便于单独验证 Manifest 配置。
System.out.println("hello from jar");
}
}构建并运行:
mvn -q clean package && java -jar target/manifest-demo-1.0.0.jar预期输出:
hello from jar直接检查生成的 Manifest
只看“能运行”还不够,发布前最好直接核对清单。下面命令适用于 Linux、macOS 或 Git Bash,并会把清单解压到当前目录的 META-INF。
jar xf target/manifest-demo-1.0.0.jar META-INF/MANIFEST.MF
grep '^Main-Class:' META-INF/MANIFEST.MF
grep '^Implementation-Title:' META-INF/MANIFEST.MF
grep '^Implementation-Version:' META-INF/MANIFEST.MF预期输出:
Main-Class: com.example.App
Implementation-Title: manifest-demo
Implementation-Version: 1.0.0如果这三行与 POM 一致,说明 Maven Archiver 已把主类和自定义元数据写入最终 JAR,而不是只存在于源码或构建配置里。
按报错类型修复启动问题
出现 no main manifest attribute 时,先确认运行的是刚刚构建的那个 JAR,再检查 maven-jar-plugin 配置是否位于 <build><plugins> 下。出现“找不到或无法加载主类”时,用 jar tf target/manifest-demo-1.0.0.jar 搜索 com/example/App.class,同时核对包名和 mainClass 是否完全一致。
如果主类能找到,但运行到某个第三方类型时报 NoClassDefFoundError,问题通常不在 Manifest 主类,而在依赖没有进入运行类路径。此时可选择生成包含依赖的可执行 JAR,或通过 Manifest 的 Class-Path 配合外置依赖;不要把“继续改 Main-Class”当作依赖缺失的修复手段。