Base64工具库：编码与解码工具类（239）

在鸿蒙（HarmonyOS）应用开发中，Base64 编码与解码是处理二进制数据与文本协议转换的基石，广泛应用于 Token 传输、图片转字符串、文件加密等场景。

鸿蒙官方提供了底层且高性能的buffer模块，同时社区也封装了更为便捷的Base64Util工具类

一、 官方原生方案：Buffer 模块实战

场景：在不引入第三方库的情况下，利用鸿蒙原生的@kit.ArkTS中的buffer模块，实现字符串与 Base64 之间的双向转换。

import { buffer } from '@kit.ArkTS'; // 1. 字符串编码为 Base64 const plainText = 'Hello HarmonyOS'; const base64Str = buffer.from(plainText, 'utf-8').toString('base64'); console.info('编码结果:', base64Str); // 输出: SGVsbG8gSGFybW9ueU9T // 2. Base64 解码还原为字符串 const decodedText = buffer.from(base64Str, 'base64').toString('utf-8'); console.info('解码结果:', decodedText); // 输出: Hello HarmonyOS // 3. 处理二进制文件（如图片）的 Base64 转换 const imageArray = new Uint8Array([0x89, 0x50, 0x4E, 0x47]); // 模拟图片字节 const imageBase64 = buffer.from(imageArray).toString('base64');

二、 社区进阶方案：Base64Util 工具类

场景：在大型项目中，将 Base64 的转换逻辑、异常捕获和 URL 安全处理封装为全局单例工具类，提升代码复用率。

import { buffer } from '@kit.ArkTS'; export class Base64Util { // 1. 标准 Base64 编码 static encode(input: string | Uint8Array): string { try { if (typeof input === 'string') { return buffer.from(input, 'utf-8').toString('base64'); } return buffer.from(input).toString('base64'); } catch (err) { console.error('Base64 编码失败:', err); return ''; } } // 2. 标准 Base64 解码 static decode(base64Str: string): string { try { return buffer.from(base64Str, 'base64').toString('utf-8'); } catch (err) { console.error('Base64 解码失败:', err); return ''; } } // 3. URL 安全的 Base64 编码（将 + 替换为 -，/ 替换为 _，去掉 =） static encodeUrlSafe(input: string): string { return Base64Util.encode(input).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); } }

三、 高阶实战：大文件流式 Base64 转换

场景：当需要处理几 MB 甚至更大的文件（如视频、高清图片）时，直接将其全部转为 Base64 会导致内存溢出（OOM）。必须采用分片读取与转换策略。

import { fileIo as fs } from '@kit.CoreFileKit'; import { Base64Util } from './Base64Util'; async function largeFileToBase64(filePath: string): Promise<string> { const file = fs.openSync(filePath, fs.OpenMode.READ_ONLY); const chunkSize = 3 * 1024; // 每次读取 3KB（3的倍数，避免 Base64 截断错位） const bufferArray = new Uint8Array(chunkSize); let base64Result = ''; let readLen = 0; while ((readLen = fs.readSync(file.fd, bufferArray)) > 0) { const chunk = bufferArray.subarray(0, readLen); base64Result += Base64Util.encode(chunk); } fs.closeSync(file); return base64Result; }

1. 内存膨胀预警：Base64 编码会使数据体积增加约33%。在处理大文件时，严禁在主线程一次性转换，必须结合TaskPool分片处理，防止引发应用崩溃。
2. URL 传参陷阱：标准的 Base64 包含+和/字符，在作为 URL 参数传递时会被浏览器或服务器错误转义。涉及网络传输时，务必使用 URL 安全的 Base64 变体（URL-Safe Base64）。
3. 去除 BOM 头：在解码由其他系统生成的 Base64 字符串时，可能会遇到隐藏的 BOM 头导致解码乱码。建议在解码前执行base64Str.trim()清理首尾空白字符。
4. 图片预览规范：如果将 Base64 字符串直接赋值给鸿蒙Image组件的src属性，必须加上数据 URI 前缀，例如：data:image/png;base64,${base64Str}，否则图片将无法渲染。

四、 官方 Base64Helper ：完整的编码与解码管道

场景：使用鸿蒙官方推荐的util.Base64Helper结合TextEncoder/TextDecoder，构建标准的字符串与 Base64 互转管道，彻底解决中文乱码问题。

import { util } from '@kit.ArkTS'; export class Base64Pipe { // 字符串 -> Base64 static encode(input: string): string { let encoder = new util.TextEncoder('utf-8'); let uint8Array = encoder.encodeInto(input); let helper = new util.Base64Helper(); return helper.encodeToStringSync(uint8Array); } // Base64 -> 字符串 static decode(input: string): string { let helper = new util.Base64Helper(); let uint8Array = helper.decodeSync(input); let decoder = util.TextDecoder.create('utf-8'); // 注意：使用静态工厂方法 return decoder.decodeToString(uint8Array); } }

五、高阶封装：支持同步/异步与 Uint8Array 转换

场景：在复杂业务中，既需要处理文本，也需要处理二进制文件（Uint8Array），同时需要异步方法避免阻塞主线程。

import { util } from '@kit.ArkTS'; export class Base64Util { private static createHelper(): util.Base64Helper { return new util.Base64Helper(); } // 二进制编码为 Base64 字符串（同步） static encodeToStrSync(array: Uint8Array): string { return Base64Util.createHelper().encodeToStringSync(array); } // Base64 解码为二进制（异步） static async decode(input: string): Promise<Uint8Array> { return Base64Util.createHelper().decode(input); } }

六、图片与 PixelMap ：Base64 与图像互转

场景：将相册选中的图片转为 Base64 字符串用于上传，或将网络返回的 Base64 字符串还原为 PixelMap 进行 UI 展示。

import { image, util } from '@kit.ArkTS'; // 将图片二进制数据转为 Base64 function pixelMapToBase64(pixelMap: image.PixelMap): string { let num = pixelMap.getPixelBytesNumber(); let readBuffer = new ArrayBuffer(num); pixelMap.readPixelsToBufferSync(readBuffer); let helper = new util.Base64Helper(); return helper.encodeToStringSync(new Uint8Array(readBuffer)); } // 将 Base64 还原为 PixelMap function base64ToPixelMap(base64Str: string, width: number, height: number): image.PixelMap { let helper = new util.Base64Helper(); let imageUint8 = helper.decodeSync(base64Str).buffer; let opts: image.InitializationOptions = { editable: true, size: { height: height, width: width } }; return image.createPixelMapSync(imageUint8, opts); }