在鸿蒙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): Promisestring { const file fs.openSync(filePath, fs.OpenMode.READ_ONLY); const chunkSize 3 * 1024; // 每次读取 3KB3的倍数避免 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; }内存膨胀预警Base64 编码会使数据体积增加约33%。在处理大文件时严禁在主线程一次性转换必须结合TaskPool分片处理防止引发应用崩溃。URL 传参陷阱标准的 Base64 包含和/字符在作为 URL 参数传递时会被浏览器或服务器错误转义。涉及网络传输时务必使用 URL 安全的 Base64 变体URL-Safe Base64。去除 BOM 头在解码由其他系统生成的 Base64 字符串时可能会遇到隐藏的 BOM 头导致解码乱码。建议在解码前执行base64Str.trim()清理首尾空白字符。图片预览规范如果将 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): PromiseUint8Array { 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); }