Spring Boot资源文件夹图片Base64编解码后损坏问题排查

问题场景 #

在Spring Boot 3.x + Java 17环境下，使用以下代码从资源文件夹加载图片并编码为Base64字符串，再通过解码方法转回图片文件时，输出的图片显示损坏，但将同一个Base64字符串放入在线工具却能正常解析。

编码代码 #

public String encodeImageAsBase64(String imagePath) {
    try {
        logger.debug("Loading image from path: {}", imagePath);
        Resource resource = resourceLoader.getResource("classpath:" + imagePath);

        if (!resource.exists()) {
            logger.error("Image not found at: {}", imagePath);
            return "";
        }

        try (InputStream inputStream = resource.getInputStream()) {
            byte[] imageBytes = inputStream.readAllBytes();
            if (imageBytes.length == 0) {
                logger.error("Empty image data for: {}", imagePath);
                return "";
            }
            String base64String = Base64.getEncoder().encodeToString(imageBytes);
            logger.info("base64String value {}", base64String);
            logger.info("Base64 encoding success, length: {}", base64String.length());
            return base64String;
        }
    } catch (Exception e) {
        logger.error("Failed to encode image: {}", imagePath, e);
        return "";
    }
}

解码代码 #

public void decodeBase64ToImage(String base64, String outputFilePath) {
    try {
        byte[] imageBytes = Base64.getDecoder().decode(base64);
        try (FileOutputStream fos = new FileOutputStream(outputFilePath)) {
            fos.write(imageBytes);
            fos.flush();
        }
        logger.info("Decoded image to: {}", outputFilePath);
        } catch (Exception e) {
        logger.error("Failed to decode image using : {}", outputFilePath, e);
    }
}

可能的原因及解决方法 #

1. 日志打印导致Base64字符串截断/转义 #

编码代码中直接打印完整的Base64字符串，多数日志框架（如Logback）会对超长字符串自动截断，或对特殊字符做转义处理。如果后续测试时用的是日志中复制的字符串，必然会导致解码失败。

解决：

• 移除logger.info("base64String value {}", base64String);这行日志，避免字符串被篡改；
• 测试时直接使用编码方法返回的字符串传给解码方法，不要复制日志内容。

2. Base64字符串包含额外字符 #

如果Base64字符串经过JSON序列化、接口返回等环节，可能会被添加额外字符（如双引号、空格、转义符），解码时这些字符会被当作有效Base64内容解析，破坏字节数据。

解决：
解码前先清理字符串，去除多余字符：

public void decodeBase64ToImage(String base64, String outputFilePath) {
    try {
        // 清理前后空格、首尾双引号
        String cleanedBase64 = base64.trim().replaceAll("^\"|\"$", "");
        byte[] imageBytes = Base64.getDecoder().decode(cleanedBase64);
        try (FileOutputStream fos = new FileOutputStream(outputFilePath)) {
            fos.write(imageBytes);
        }
        File outputFile = new File(outputFilePath);
        logger.info("Decoded image to: {}, file size: {}", outputFilePath, outputFile.length());
    } catch (Exception e) {
        logger.error("Failed to decode image to: {}", outputFilePath, e);
    }
}

3. 资源加载时字节读取不完整 #

虽然readAllBytes()在Java17中是一次性读取全部字节，但仍可能出现资源长度与读取字节数不匹配的情况。

解决：
在编码时添加长度校验，确认读取的字节数与原文件一致：

public String encodeImageAsBase64(String imagePath) {
    try {
        logger.debug("Loading image from path: {}", imagePath);
        Resource resource = resourceLoader.getResource("classpath:" + imagePath);

        if (!resource.exists()) {
            logger.error("Image not found at: {}", imagePath);
            return "";
        }

        long expectedLength = resource.contentLength();
        try (InputStream inputStream = resource.getInputStream()) {
            byte[] imageBytes = inputStream.readAllBytes();
            if (imageBytes.length == 0) {
                logger.error("Empty image data for: {}", imagePath);
                return "";
            }
            if (imageBytes.length != expectedLength) {
                logger.warn("Image bytes mismatch: expected {} but got {}", expectedLength, imageBytes.length);
            }
            String base64String = Base64.getEncoder().encodeToString(imageBytes);
            logger.info("Base64 encoding success, length: {}", base64String.length());
            return base64String;
        }
    } catch (Exception e) {
        logger.error("Failed to encode image: {}", imagePath, e);
        return "";
    }
}

4. 文件写入时的隐性问题 #

手动调用fos.flush()多余（try-with-resources会自动处理缓冲区刷新），但如果输出路径无写入权限、文件被其他进程占用，也可能导致文件损坏。

解决：

• 检查输出路径的写入权限；
• 解码完成后对比原文件与输出文件的大小，确认字节数一致。

内容的提问来源于stack exchange，提问作者gibyalex