运行JAR包时提示“no main manifest attribute”怎么办？

Question

运行JAR包时提示“no main manifest attribute”，本质是JAR包的`META-INF/MANIFEST.MF`文件中缺少`Main-Class`声明，导致JVM无法识别入口类。常见原因包括：使用`jar cvf xxx.jar *.class`等基础命令打包时未指定主类；Maven项目未配置`maven-jar-plugin`或`spring-boot-maven-plugin`（Spring Boot需用`mvn spring-boot:repackage`生成可执行jar）；Gradle中未设置`application.mainClass`。解决方法：① 手动编辑MANIFEST.MF添加`Main-Class: com.example.Main`（注意冒号后空格及换行符规范）；② Maven中在`pom.xml`的`maven-jar-plugin`里配置``；③ 推荐使用构建工具自动生成——Maven执行`mvn clean package`（确保有正确插件配置），而非手动jar命令。验证可用`jar -tf xxx.jar | grep MANIFEST`和`jar -xf xxx.jar META-INF/MANIFEST.MF && cat META-INF/MANIFEST.MF`。核心原则：可执行JAR必须由构建工具“声明式”生成，而非简单归档。

Answer 1

```html

一、现象层：从命令行错误到JVM语义解析

执行 java -jar app.jar 时抛出 no main manifest attribute，表面是CLI报错，实则是JVM在加载JAR时对 META-INF/MANIFEST.MF 的**强制契约校验失败**。该错误不涉及类路径、字节码兼容性或依赖缺失，而是JVM启动协议层面的“准入检查”——即：可执行JAR必须携带明确的入口声明。

二、机制层：MANIFEST.MF 的规范约束与JVM加载流程

JVM规范（JLS §12.1.4）明确定义：当使用 -jar 参数时，JVM会严格解析 META-INF/MANIFEST.MF，并仅识别以 Main-Class: 开头的属性行（注意冒号后**必须跟一个空格**，且整行不能有尾部空格或制表符）。若该行缺失、拼写错误（如 Mainclass）、缩进异常或换行符为 \r（Windows CRLF 在某些Linux容器中可能被截断），均导致解析失败。

三、归因层：三大主流构建场景下的典型失配点

构建方式	常见疏漏	本质问题
原始 jar 命令	jar cvf app.jar *.class 未用 -e 或 -m	将JAR视为静态归档文件，而非可执行程序包
Maven（非Spring Boot）	未配置 maven-jar-plugin 或遗漏 <mainClass>	默认 jar:jar 目标生成的是库JAR，无运行时语义
Gradle Application Plugin	application.mainClass = "com.example.Main" 未设置或拼写错误	distZip/installDist 不影响 jar 任务，需显式启用 application 插件并绑定

四、诊断层：结构化验证流程（含Shell命令链）

推荐按顺序执行以下验证，形成闭环诊断：

1. jar -tf app.jar | grep -i 'META-INF/MANIFEST.MF' —— 确认文件存在
2. jar -xf app.jar META-INF/MANIFEST.MF && head -n 20 META-INF/MANIFEST.MF —— 检查格式（行末不可有空格，最后一行必须为空行）
3. file -i META-INF/MANIFEST.MF —— 验证编码为 us-ascii（UTF-8含BOM将导致解析失败）
4. od -c META-INF/MANIFEST.MF | head -10 —— 查看实际字节，确认换行符为 \n（LF）

五、解法层：从临时修复到工程化实践

graph TD A[问题触发] --> B{构建方式} B -->|原始jar命令| C[手动补MANIFEST
jar cvfm app.jar MANIFEST.MF *.class] B -->|Maven| D[配置maven-jar-plugin
或spring-boot-maven-plugin] B -->|Gradle| E[启用application插件
并设置mainClass] C --> F[风险：易出错/难复现/无法CI集成] D & E --> G[推荐：声明式构建+版本锁定+可审计]

六、高阶陷阱：Spring Boot的特殊性与repackage语义

Spring Boot项目若仅执行 mvn package，生成的是普通WAR/JAR（含 Main-Class: org.springframework.boot.loader.JarLauncher），但其内部嵌套结构依赖 spring-boot-maven-plugin 的 repackage 目标重写整个JAR布局。未执行 mvn spring-boot:repackage 或插件未绑定到 package 生命周期，将导致MANIFEST中 Start-Class 存在而 Main-Class 缺失，或 Loader-Class 路径错误。这是Boot与标准Java SE JAR最根本的分水岭。

七、防御性实践：CI/CD流水线中的Manifest守门人

在GitHub Actions或Jenkins中，可在构建后插入校验步骤：

#!/bin/bash
JAR_FILE=target/app.jar
if ! jar -xf "$JAR_FILE" META-INF/MANIFEST.MF 2>/dev/null; then
  echo "ERROR: MANIFEST.MF missing"; exit 1
fi
if ! grep -q "^Main-Class: " META-INF/MANIFEST.MF; then
  echo "ERROR: Main-Class not declared"; exit 1
fi
if [[ $(tail -c1 META-INF/MANIFEST.MF | wc -l) -ne 1 ]]; then
  echo "ERROR: MANIFEST lacks trailing newline"; exit 1
fi

八、延伸思考：模块化JDK（JPMS）与Module-Path的协同演进

在JDK 9+中，若应用采用模块化（module-info.java），则 Main-Class 并非唯一入口标识。可通过 java --module-path app.jar --module com.example/com.example.Main 绕过MANIFEST依赖。但此模式要求JAR已通过 jlink 或 jpackage 构建为自包含模块镜像，且丧失传统 -jar 的简洁性。这标志着可执行单元正从“清单驱动”向“模块驱动”迁移。

九、知识图谱锚点：关联技术栈与规范引用

• JVM规范 §5.3.1 “The Class Loader Subsystem” —— 定义JAR入口发现逻辑
• Java ARchive (JAR) File Format Specification（JSR 57） —— MANIFEST语法白皮书
• Maven Core Lifecycle Bindings —— 解释为何 maven-jar-plugin:2.4 后默认不绑定到 package
• Spring Boot Reference Doc §89.1 “Executable Jar Format” —— 嵌套JAR与Launcher类加载器拓扑

十、反模式警示：为什么“手动编辑MANIFEST.MF再重打包”是反工程实践

该操作破坏了构建的幂等性与可重现性：每次修改需重新计算SHA-256校验和、更新时间戳、处理签名块（若JAR已签名则会失效），且无法纳入Git追踪。更严重的是，它绕过了编译器对主类存在的静态检查（如Maven的 compiler-plugin 会验证 Main-Class 是否真实存在并含 public static void main(String[])）。现代CI/CD要求“一次构建，处处运行”，手工干预直接违背这一铁律。

```