Java Base64 流式编码怎么避免一次加载大文件

处理几百 MB 甚至更大的文件时，先调用 Files.readAllBytes()，再交给 Base64.getEncoder().encodeToString()，通常会同时保留原始字节数组和膨胀后的 Base64 字符串，内存峰值很容易超过预期。更稳妥的做法是让编码器包住输出流，输入端用固定缓冲区循环读取，数据到达就写出。

官方地址：https://docs.oracle.com/en/java/javase/27/docs/api/java.base/java/util/Base64.Encoder.html

先定位内存峰值：问题不只是一行 API

下面这种写法简单，但它把两个大对象都放进堆里：原文件先变成 byte[]，编码后又得到一份更大的文本。

// 反例：原始字节和 Base64 字符串可能同时存活
byte[] source = Files.readAllBytes(input);
String encoded = Base64.getEncoder().encodeToString(source);
Files.writeString(output, encoded, StandardCharsets.ISO_8859_1);

Base64 的结果大约按每 3 个输入字节变成 4 个字符计算，实际还要考虑 Java 字符串和数组对象的开销。如果目标只是写文件、发请求体或交给另一个输出管道，就没有必要先构造完整字符串。

用包装输出流把大文件拆成固定块

标准库的 Encoder.wrap(OutputStream) 返回一个编码输出流。调用方只负责把原始字节写入它，编码后的字节会继续流向底层目标。

// 说明：输入按 32 KiB 分块，编码器持续写入目标文件
Path input = Path.of("payload.bin");
Path output = Path.of("payload.b64");
Base64.Encoder encoder = Base64.getEncoder();

try (InputStream in = Files.newInputStream(input);
     OutputStream fileOut = Files.newOutputStream(output);
     OutputStream encodedOut = encoder.wrap(fileOut)) {
    // 固定缓冲区避免按文件大小申请 byte[]
    byte[] buffer = new byte[32 * 1024];
    int n;
    while ((n = in.read(buffer)) != -1) {
        // 只写本次读取到的 n 个字节，避免把旧数据重复编码
        encodedOut.write(buffer, 0, n);
    }
} // 先关闭 encodedOut，尾部补位随后写入 fileOut

这里有三个容易漏掉的细节：write 的长度必须使用本次读取的 n；缓冲区大小只是吞吐与内存的折中，不需要等于文件大小；最内层的 encodedOut 要参与 try-with-resources。

关闭比 flush 更关键：最后两个字节也要有结果

Base64 以 3 个输入字节为一组。文件长度不是 3 的整数倍时，编码器需要在结束时写出尾部字符和可能的 = 补位。官方文档明确建议使用后及时关闭包装流，而且关闭它也会关闭底层输出流。

因此不要把编码流当成普通缓冲流，只在循环结束后调用 flush() 就离开。上面的资源声明把关闭责任放在同一处，既能完成尾部编码，也能让文件句柄按确定顺序释放。

基本、URL 和无补位编码不要混用

如果输出是 HTTP 请求体，最好直接把 encodedOut 接到请求库提供的输出流；如果必须得到字符串，流式写文件并不会自动让字符串变小，应该先确认接收协议是否真的要求完整字符串。

复查清单：大文件、异常和资源责任

• 输入循环使用 n，没有把缓冲区尾部旧字节写进去。
• 只保留固定大小的读缓冲区，没有按文件长度申请数组。
• 编码包装流在正常和异常路径都会关闭，输出目标不会留下半截未收尾的 Base64。
• 用长度为 1、2、3、4 的小输入验证解码可逆，再用大文件检查堆使用和目标文件长度。
• 若底层输出流由调用方继续使用，先确认包装流关闭会连带关闭底层流；需要不同生命周期时应重新设计流边界。

常见问题

流式 Base64 会不会让结果变短？

不会。它主要改变内存占用和写出时机，编码规则仍会产生约四分之一的体积膨胀。

为什么关闭后才出现最后的 =？

因为编码器要等到确认输入结束，才能处理不足三个字节的尾部。关闭包装流就是告诉它输入已经结束。

能不能每次循环都创建一个 Base64 编码器？

不应该这样做。一个包装流应覆盖完整输入，循环只写入同一个编码输出流，否则分块边界可能被错误当成独立消息边界。