Java JAR清单文件自定义属性的正确添加与读取方法

JAR清单文件（MANIFEST.MF）基础

JAR文件是Java平台常用的打包格式，而META-INF/MANIFEST.MF文件是JAR包的元数据文件，它包含了关于JAR包及其内容的各种信息，例如版本号、入口类、依赖关系等。清单文件采用键值对的形式组织信息，每个属性占用一行，并且遵循严格的格式规范。Java的java.util.jar.Manifest类负责解析这些清单文件，并提供对其中属性的访问。

程序化修改JAR清单文件

在某些场景下，我们可能需要动态地向现有JAR文件的清单中添加自定义属性，例如部署版本信息、配置参数等。直接修改JAR文件内部的MANIFEST.MF需要通过Java的NIO.2文件系统API来完成。

挂载JAR文件系统

Java 7引入的NIO.2文件系统API允许我们将JAR文件视为一个文件系统来操作，这使得我们可以像操作普通文件一样，读写JAR内部的文件。

Map env = new HashMap<>();
env.put("create", "true"); // 如果JAR不存在则创建，这里我们是修改现有JAR
// 将JAR文件转换为URI，以便FileSystems可以识别为JAR文件系统
URI jarUri = jarFileToURI(jar);
try (FileSystem fileSystem = FileSystems.newFileSystem(jarUri, env)) {
    // 后续操作在try-with-resources块中进行，确保FileSystem正确关闭
    // ...
}

读取与修改清单内容

要修改清单文件，首先需要读取其现有内容。MANIFEST.MF通常是一个文本文件，我们可以将其内容读入内存，然后进行修改。

立即学习“Java免费学习笔记（深入）”；

Path manifestPath = fileSystem.getPath("/META-INF/MANIFEST.MF");
ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
Files.copy(manifestPath, byteArrayOutputStream);

// 将清单字节转换为字符串，并构建StringBuilder以便追加
StringBuilder manifestData = new StringBuilder(byteArrayOutputStream.toString().trim());

关键：确保正确的行终止符

这是导致自定义属性无法被Manifest类正确读取的常见陷阱。MANIFEST.MF文件的规范要求每个属性行，包括最后一个属性行，都必须以换行符（\n）结束。如果最后一个自定义属性之后没有换行符，Manifest解析器可能会将其忽略。

错误的添加方式（可能导致问题）：

manifestData.append("\n");
manifestData.append("Deployments-Version: ");
manifestData.append(testVersion); // 缺少末尾的换行符

正确的添加方式：

Mureka

Mureka是昆仑万维最新推出的一款AI音乐创作工具，输入歌词即可生成完整专属歌曲。

下载

manifestData.append("\n"); // 确保新属性前有换行
manifestData.append("Deployments-Version: ");
manifestData.append(testVersion);
manifestData.append("\n"); // 关键：确保新属性后有换行，作为该行的终止符

将修改写回JAR

修改完成后，将更新后的清单内容写回JAR文件中的MANIFEST.MF路径。

Files.copy(new ByteArrayInputStream(manifestData.toString().getBytes()), manifestPath,
        StandardCopyOption.REPLACE_EXISTING);

程序化读取JAR清单属性

一旦JAR文件被修改并保存，我们可以通过java.util.jar.JarFile类来读取其清单属性。

使用JarFile类读取

JarFile类提供了getManifest()方法来获取JAR文件的Manifest对象。通过这个对象，我们可以访问主属性（Main Attributes）以及各个条目（Entries）的属性。

try (JarFile jarFile = new JarFile(jar)) {
    Manifest manifest = jarFile.getManifest();
    if (manifest != null) {
        // 获取主属性集合
        Attributes mainAttributes = manifest.getMainAttributes();
        // 通过键名获取自定义属性的值
        String deploymentVersion = mainAttributes.getValue("Deployments-Version");
        System.out.println("读取到的 Deployments-Version: " + deploymentVersion);
    } else {
        System.out.println("JAR文件没有清单或清单无法读取。");
    }
} catch (IOException e) {
    e.printStackTrace();
}

如果修改清单时没有遵循严格的格式（特别是缺少最后的换行符），即使通过文本编辑器或压缩工具（如7zip）能看到自定义属性，JarFile.getManifest()在解析时也可能无法识别该属性，导致getValue()返回null。

完整示例与运行验证

以下是一个完整的Java代码示例，演示了如何向现有JAR文件添加自定义清单属性并随后正确读取它们。

import java.io.*;
import java.net.URI;
import java.net.URISyntaxException;
import java.nio.file.*;
import java.util.HashMap;
import java.util.Map;
import java.util.jar.Attributes;
import java.util.jar.JarFile;
import java.util.jar.Manifest;

public class JarManifestModifier {

    public static void main(String[] args) throws IOException, URISyntaxException {
        // 假设JAR文件路径，请替换为您的实际路径
        File jar = new File("C:\\Users\\employee1234\\Desktop\\auth-0.1.3.jar");
        String testVersion = "1.2.3";
        String customAttributeName = "Deployments-Version";

        // 1. 修改JAR文件中的MANIFEST.MF
        System.out.println("--- 尝试修改JAR清单文件 ---");
        Map env = new HashMap<>();
        env.put("create", "true"); // 允许创建文件系统

        try (FileSystem fileSystem = FileSystems.newFileSystem(jarFileToURI(jar), env)) {
            Path manifestPath = fileSystem.getPath("/META-INF/MANIFEST.MF");

            // 读取现有清单内容
            ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
            Files.copy(manifestPath, byteArrayOutputStream);

            // 将清单字节转换为字符串并构建StringBuilder
            StringBuilder manifestData = new StringBuilder(byteArrayOutputStream.toString().trim());

            // 添加自定义清单属性，确保末尾有换行符
            // 注意：如果manifestData.toString().trim()结果是空字符串，则直接添加
            if (manifestData.length() > 0) {
                manifestData.append("\n"); // 确保新属性前有换行
            }
            manifestData.append(customAttributeName).append(": ").append(testVersion).append("\n"); // 关键：新属性行末尾必须有换行

            // 将修改后的清单内容写回JAR
            Files.copy(new ByteArrayInputStream(manifestData.toString().getBytes()), manifestPath,
                    StandardCopyOption.REPLACE_EXISTING);

            System.out.println("清单文件修改成功，添加属性: " + customAttributeName + ": " + testVersion);
        } catch (Exception e) {
            System.err.println("修改JAR清单文件失败: " + e.getMessage());
            e.printStackTrace();
            return; // 修改失败则退出
        }

        // 2. 尝试从修改后的JAR中读取自定义属性
        System.out.println("\n--- 尝试从修改后的JAR中读取自定义属性 ---");
        try (JarFile jarFile = new JarFile(jar)) {
            Manifest manifest = jarFile.getManifest();
            if (manifest != null) {
                String retrievedVersion = manifest.getMainAttributes().getValue(customAttributeName);
                System.out.println("从JAR中读取到的 " + customAttributeName + ": " + retrievedVersion);
                if (testVersion.equals(retrievedVersion)) {
                    System.out.println("自定义属性读取成功！");
                } else {
                    System.out.println("自定义属性读取失败或值不匹配！");
                }
            } else {
                System.out.println("JAR文件没有清单或清单无法读取。");
            }
        } catch (IOException e) {
            System.err.println("读取JAR清单文件失败: " + e.getMessage());
            e.printStackTrace();
        }
    }

    // 辅助方法：将File对象转换为JAR文件系统URI
    private static URI jarFileToURI(File jarFile) throws URISyntaxException {
        String sp = slashify(jarFile.getAbsoluteFile().getPath(), false);
        if (sp.startsWith("//"))
            sp = "//" + sp;
        return new URI("jar:file", null, sp, null);
    }

    // 辅助方法：将路径转换为斜杠分隔格式
    private static String slashify(String path, boolean isDirectory) {
        String p = path;
        if (File.separatorChar != '/')
            p = p.replace(File.separatorChar, '/');
        if (!p.startsWith("/"))
            p = "/" + p;
        if (!p.endsWith("/") && isDirectory)
            p = p + "/";
        return p;
    }
}

运行前请注意：

• 将C:\\Users\\employee1234\\Desktop\\auth-0.1.3.jar替换为您的实际JAR文件路径。
• 此操作会直接修改您的JAR文件，建议在运行前备份原始JAR文件。

注意事项与最佳实践

1. 清单文件格式的严格性：MANIFEST.MF文件对格式非常敏感。除了本文强调的行终止符，还包括：
   • 每行最大长度通常为72字节（超出部分需要通过空格缩进继续）。
   • 键值对之间必须用冒号和空格分隔（Key: Value）。
   • 属性名不区分大小写，但通常建议保持一致性。
2. 错误处理：在实际应用中，务必对文件操作和JAR解析过程中可能出现的IOException进行适当的异常处理。
3. 调试技巧：如果自定义属性仍然无法读取，可以使用文本编辑器（如Notepad++、VS Code）或压缩工具（如7-Zip、WinRAR）打开JAR文件，检查META-INF/MANIFEST.MF的内容，确认自定义属性是否存在且格式正确（特别是末尾的换行符）。
4. 避免冲突：自定义属性的名称应避免与标准清单属性（如Manifest-Version、Created-By、Main-Class等）冲突。
5. 替代方案：对于更复杂的JAR操作或构建流程，可以考虑使用构建工具（如Maven、Gradle）或专门的库（如Apache Ant的JAR任务），它们通常提供了更健壮和易用的API来管理JAR文件及其清单。

通过理解并遵循MANIFEST.MF文件的严格格式要求，特别是确保每个属性行（包括最后一个）都以换行符结束，可以有效解决Java应用程序在动态修改JAR清单后无法正确读取自定义属性的问题。