Hutool实现字节流与Base64编码转换教程

最新推荐文章于 2026-03-27 18:19:45 发布

原创最新推荐文章于 2026-03-27 18:19:45 发布 · 1.8k 阅读

7 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#hutool #base64 #字节流

JAVA 专栏收录该内容

73 篇文章

订阅专栏

一、基础准备

1.1 什么是Base64编码？

Base64是一种二进制到文本的编码方式，将3字节（24位）的二进制数据转换为4个可打印的ASCII字符（每6位一组），常用于在文本协议（如JSON、XML、HTTP）中安全传输二进制数据（如图片、文件）。
Base64头（Header）是标识Base64数据类型的可选前缀，常见格式为data:[<mediatype>][;base64],，例如图片的Base64头为data:image/png;base64,，用于明确数据的MIME类型。

1.2 Hutool工具简介

Hutool是Java生态中轻量级、全场景的工具类库，封装了大量实用方法，其中cn.hutool.core.codec.Base64类提供了字节流与Base64字符串的高效转换功能，支持普通Base64、URL安全Base64、MIME类型Base64等多种模式。

1.3 引入Hutool依赖

以Maven项目为例，在pom.xml中添加以下依赖：

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.16</version> <!-- 建议使用最新稳定版 -->
</dependency>

二、字节流转Base64编码（无头）

2.1 核心方法

使用Base64.encode()方法可直接将字节数组转换为Base64字符串：

import cn.hutool.core.codec.Base64;

public class ByteToBase64Example {
    public static void main(String[] args) {
        String originalText = "Hello, Hutool!";
        byte[] bytes = originalText.getBytes(); // 字符串转字节数组
        
        // 字节流转Base64（无头）
        String base64Str = Base64.encode(bytes);
        System.out.println("Base64编码结果（无头）：" + base64Str);
    }
}

输出结果：
SGVsbG8sIEh1dG9vbCE=

2.2 指定字符集

若需处理非UTF-8字符（如中文），可通过CharsetUtil指定字符集：

import cn.hutool.core.codec.Base64;
import cn.hutool.core.util.CharsetUtil;

public class ByteToBase64WithCharset {
    public static void main(String[] args) {
        String originalText = "你好，Hutool！";
        byte[] bytes = originalText.getBytes(CharsetUtil.UTF_8); // 明确指定UTF-8
        
        String base64Str = Base64.encode(bytes);
        System.out.println("Base64编码结果（UTF-8）：" + base64Str);
    }
}

输出结果：
5L2g5aW977yM5LiW55WMhQ==

三、Base64解码为字节流

使用Base64.decode()方法可将Base64字符串解码为字节数组：

import cn.hutool.core.codec.Base64;

public class Base64ToByteExample {
    public static void main(String[] args) {
        String base64Str = "SGVsbG8sIEh1dG9vbCE=";
        
        // Base64解码为字节数组
        byte[] decodedBytes = Base64.decode(base64Str);
        String decodedText = new String(decodedBytes); // 字节数组转字符串
        
        System.out.println("解码后的文本：" + decodedText);
    }
}

输出结果：
Hello, Hutool！

四、带Base64头的编码（适用于文件/图片传输）

4.1 为什么需要Base64头？

当Base64数据用于HTML/CSS的src属性（如<img src="data:image/png;base64,...">）或HTTP Content-Type时，需要添加Base64头以明确数据类型，避免解析错误。

4.2 实现步骤

步骤1：获取字节流（以图片为例）

使用Hutool的FileUtil.readBytes()读取图片文件的字节流：

import cn.hutool.core.io.FileUtil;

public class ImageToBase64WithHeader {
    public static void main(String[] args) {
        // 图片路径（替换为实际路径）
        String imagePath = "D:/test.png";
        byte[] imageBytes = FileUtil.readBytes(imagePath); // 读取图片字节流
    }
}

步骤2：添加Base64头

根据文件类型选择合适的MIME类型，拼接Base64头：

public class ImageToBase64WithHeader {
    public static void main(String[] args) {
        String imagePath = "D:/test.png";
        byte[] imageBytes = FileUtil.readBytes(imagePath);
        
        // 添加Base64头（图片类型为PNG）
        String base64WithHeader = "data:image/png;base64," + Base64.encode(imageBytes);
        System.out.println("带Base64头的编码结果：" + base64WithHeader);
    }
}

输出结果：
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...（省略部分字符）

步骤3：验证结果

将输出的Base64字符串复制到在线工具（如Base64 to Image Converter），即可还原为原始图片，验证编码正确性。

五、常见问题解决

5.1 编码后字符串包含换行符？

Hutool的Base64.encode()默认会添加换行符（符合MIME标准），若需去除，可使用Base64.encodeToStr()方法：

String base64Str = Base64.encodeToStr(bytes); // 无换行符

5.2 如何处理URL中的Base64？

若需将Base64用于URL参数（避免+、/等特殊字符），可使用Base64.encodeUrlSafe()方法：

String urlSafeBase64 = Base64.encodeUrlSafe(bytes); // 替换+为-，/为_

5.3 文件不存在怎么办？

读取文件字节流时，需处理FileNotFoundException异常：

import java.io.FileNotFoundException;

public class FileToBase64Safe {
    public static void main(String[] args) {
        String imagePath = "D:/nonexistent.png";
        try {
            byte[] bytes = FileUtil.readBytes(imagePath);
            String base64Str = Base64.encode(bytes);
            System.out.println(base64Str);
        } catch (FileNotFoundException e) {
            System.err.println("文件未找到：" + imagePath);
        }
    }
}