no main manifest attribute错误如何解决？

Question

当执行 `java -jar app.jar` 时出现“no main manifest attribute”错误，表示 JAR 文件的 MANIFEST.MF 中未定义主类（Main-Class）。JVM 无法识别程序入口点。解决方法是在打包时确保 manifest 文件中包含 `Main-Class: com.example.Main`。使用 Maven 可配置 maven-compiler-plugin 或 maven-jar-plugin 指定主类；Gradle 中可通过 bootJar 或 jar 任务设置 mainClassName。手动编写 MANIFEST.MF 时需注意最后一行换行符。推荐使用 Spring Boot 或可执行 JAR 打包插件自动化处理。

Answer 1

1. 问题现象与初步诊断

当执行 java -jar app.jar 命令时，控制台输出错误信息：no main manifest attribute, in app.jar。这表明 JVM 在尝试启动 JAR 文件时，无法找到程序的入口点。JAR 包中的 META-INF/MANIFEST.MF 文件缺少关键属性 Main-Class，该属性用于指定包含 public static void main(String[] args) 方法的主类。

此问题在开发、构建和部署 Java 应用程序过程中极为常见，尤其是在手动打包或构建配置不完整的情况下。对于拥有五年以上经验的开发者而言，虽然基础，但其背后涉及的构建工具链、打包机制及可执行 JAR 规范仍值得深入探讨。

2. 深入分析：JAR 可执行性机制

JVM 在执行 java -jar 命令时，会自动查找 JAR 包根目录下的 META-INF/MANIFEST.MF 文件，并从中读取 Main-Class 属性值作为程序入口。若该属性缺失或格式错误（如缺少换行符），则抛出“no main manifest attribute”异常。

以下是典型的 MANIFEST.MF 文件内容示例：

Manifest-Version: 1.0
Created-By: 17 (Oracle Corporation)
Main-Class: com.example.Main

注意：文件末尾必须有一个换行符，否则最后一行可能被忽略，导致 Main-Class 实际未生效。

3. 构建工具解决方案对比

构建工具	插件/任务	配置方式	适用场景
Maven	maven-jar-plugin	<mainClass>com.example.Main</mainClass>	标准 Java 项目
Maven	maven-shade-plugin	在 <manifestItems> 中设置 Main-Class	生成 fat jar
Gradle	jar	mainClassName = 'com.example.Main'	传统 Gradle 项目
Gradle	bootJar	mainClass = 'com.example.Main'	Spring Boot 项目
Ant	jar task	manifest 元素中指定 attribute name="Main-Class"	遗留系统维护

4. Maven 配置详解

在 pom.xml 中使用 maven-jar-plugin 显式指定主类：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.3.0</version>
      <configuration>
        <archive>
          <manifest>
            <mainClass>com.example.Main</mainClass>
            <addClasspath>true</addClasspath>
          </manifest>
        </archive>
      </configuration>
    </plugin>
  </plugins>
</build>

该配置确保生成的 JAR 文件中 MANIFEST.MF 自动包含正确的 Main-Class 属性。

5. Gradle 配置实践

在 build.gradle 中配置主类：

jar {
    manifest {
        attributes 'Main-Class': 'com.example.Main'
    }
}
// 或使用 Spring Boot 插件
bootJar {
    mainClass = 'com.example.Main'
}

Spring Boot 推荐使用 bootJar 任务，它不仅设置主类，还打包所有依赖并生成可独立运行的 fat jar。

6. 手动创建 MANIFEST.MF 的注意事项

• 文件编码应为 ISO-8859-1（JAR 规范要求）
• 每行最大长度为 72 字节，超长需折行（以空格开头）
• 文件末尾必须包含换行符，否则最后一行无效
• 属性名与值之间使用冒号加空格分隔：Main-Class: com.example.Main
• 避免 BOM（字节顺序标记），可能导致解析失败

7. 自动化与最佳实践推荐

1. 优先使用 Spring Boot 的 spring-boot-maven-plugin 或 spring-boot-gradle-plugin，自动处理主类声明与依赖打包
2. 在 CI/CD 流水线中加入 JAR 可执行性验证步骤，例如通过脚本解压并检查 MANIFEST.MF 内容
3. 使用 jar -tf app.jar 查看 JAR 内容，确认 META-INF/MANIFEST.MF 存在
4. 通过 unzip -p app.jar META-INF/MANIFEST.MF 直接查看清单文件内容
5. 结合 Archiver 或 Build Scan 工具进行构建过程审计
6. 对多模块项目，确保主模块正确引用主类配置
7. 避免手动编辑 MANIFEST.MF，交由构建工具自动生成
8. 启用构建日志详细模式，排查插件是否实际应用了配置

8. 故障排查流程图

graph TD
    A[执行 java -jar app.jar] --> B{报错: no main manifest attribute?}
    B -- 是 --> C[检查 JAR 是否包含 META-INF/MANIFEST.MF]
    C -- 否 --> D[重新打包，确保生成清单文件]
    C -- 是 --> E[查看 MANIFEST.MF 内容]
    E --> F{包含 Main-Class 属性?}
    F -- 否 --> G[在构建配置中添加 Main-Class]
    F -- 是 --> H{属性值正确且末尾有换行?}
    H -- 否 --> I[修正格式并重新打包]
    H -- 是 --> J[尝试运行]
    J --> K[成功运行]
    G --> L[使用 maven-jar-plugin 或 bootJar 配置]
    L --> C

9. 高级场景：模块化与 JPMS

在 Java 9+ 模块化项目中，若使用 module-info.java，仍需在构建时显式指定 Main-Class，因为模块描述符不替代 MANIFEST.MF 中的入口定义。此外，可结合 jlink 生成自定义运行时镜像，规避 JAR 执行问题。

某些容器化部署场景中，建议直接调用 java -cp app.jar com.example.Main 而非 -jar，以绕过清单依赖，但这牺牲了可执行 JAR 的便捷性。

10. 总结性扩展：从构建到运维的闭环管理

“no main manifest attribute” 不仅是配置缺失，更是构建流程完整性的一种体现。现代 DevOps 实践中，应将此类元数据验证纳入自动化测试范畴。例如，在发布前通过脚本断言 MANIFEST.MF 中存在有效 Main-Class，从而实现质量左移。

对于大型企业级系统，建议建立统一的构建模板（Maven Archetype 或 Gradle Plugin），预置正确的主类配置、签名策略、安全属性等，减少人为错误。