第3.4篇图片压缩与 Base64 编解码系列HarmonyOS 从入门到实践 · 画伴梦工厂实战难度⭐⭐ 进阶前置知识2.4 涂鸦画布进阶涉及源文件products/default/src/main/ets/services/AIGenerationService.ets、products/default/src/main/ets/services/ImageRecognitionService.ets在之前的文章中我们已经学习了如何通过 HTTP 网络请求调用 AI 服务。但无论是文生图还是图生视频 APIAI 服务接收的图片数据通常以Base64 编码的形式传输而非直接传递文件 URI。同时大尺寸图片直接编码会导致请求体过大、传输缓慢甚至超时。因此图片压缩 Base64 编解码成为连接本地图片与远程 AI 服务的核心中间环节。本文将基于画伴梦工厂中AIGenerationService图生视频服务和ImageRecognitionService图像识别服务的真实代码完整拆解 HarmonyOS 下图片文件读取、压缩、编码、解码的全流程。一、为什么需要图片压缩 Base641.1 图片传输的三大挑战向 AI API 发送图片时我们面临三个核心约束约束说明典型值API 请求体大小限制部分 API 对请求体有隐性或显性上限2MB10MB传输效率Base64 编码后体积膨胀约 33%每 3 字节→4 字符原始 1MB → Base64 约 1.37MB识别/生成质量过高的图片分辨率对 AI 识别增益有限但传输成本剧增1024px 边缘已足够1.2 项目中的目标值项目中两个服务分别设定了不同的目标压缩大小// AIGenerationService图生视频constTARGET_UPLOAD_IMAGE_BYTES:number900*1024;// 900KB 目标constCOMPRESSED_IMAGE_QUALITY:number78;constCOMPRESSED_IMAGE_MAX_EDGE:number1280;// ImageRecognitionService图像识别constRECOGNITION_IMAGE_TARGET_BYTES:number520*1024;// 520KB 目标constRECOGNITION_IMAGE_MAX_EDGE:number1024;可以看到图生视频服务容忍更高的图片大小900KB因为生成的视频质量依赖于输入图片细节而图像识别服务仅需理解画面内容目标更小520KB边缘也限制在 1024px。二、fileIo 流式读取从本地文件到 ArrayBuffer所有图片处理的第一步是将图片文件从磁盘读取为内存中的ArrayBuffer。HarmonyOS 提供了kit.CoreFileKit中的fileIo模块来完成这一操作。2.1 基础读取流程以ImageRecognitionService.readImageAsArrayBuffer为例privatestaticreadImageAsArrayBuffer(imageUri:string):ArrayBuffer{constcandidates:string[]ImageRecognitionService.getReadableUriCandidates(imageUri);letlastError:Error|undefinedundefined;for(leti0;icandidates.length;i){try{constfilefileIo.openSync(candidates[i],fileIo.OpenMode.READ_ONLY);try{conststatfileIo.statSync(file.fd);if(stat.sizeMAX_IMAGE_BYTES){// 12MB 硬限制thrownewError(图片超过 12MB请重新拍摄或压缩后再识别);}constbuffernewArrayBuffer(stat.size);constreadSizefileIo.readSync(file.fd,buffer);if(readSizestat.size){returnbuffer;}returnbuffer.slice(0,readSize);}finally{fileIo.closeSync(file);}}catch(error){lastErrorerrorasError;}}thrownewError(无法读取图片);}2.2 fileIo 关键 API 拆解API作用使用要点fileIo.openSync(path, mode)打开文件返回File对象READ_ONLY只读模式path必须是沙箱内路径fileIo.statSync(fd)获取文件状态信息.size属性获取文件字节长度fileIo.readSync(fd, buffer)将文件内容读入ArrayBuffer返回实际读取的字节数readSizefileIo.closeSync(file)关闭文件句柄必须在 finally 块中执行防止句柄泄漏2.3 候选路径Candidate Fallback机制细心的读者会发现代码中并没有直接用原始imageUri打开文件而是调用了getReadableUriCandidates。这是因为从相机或相册获取的 URI 可能有多种格式file://前缀、content://协议、URL 编码等不同 HarmonyOS 版本或设备返回的 URI 格式存在差异。AIGenerationService中的实现更为完善privatestaticgetReadableUriCandidates(uri:string):string[]{constcandidates:string[][];AIGenerationService.addCandidate(candidates,uri);constqueryIndexuri.indexOf(?);if(queryIndex0){AIGenerationService.addCandidate(candidates,uri.substring(0,queryIndex));}if(uri.startsWith(file://)){constpathuri.substring(7);AIGenerationService.addCandidate(candidates,path);constpathQueryIndexpath.indexOf(?);if(pathQueryIndex0){AIGenerationService.addCandidate(candidates,path.substring(0,pathQueryIndex));}}// 对每个候选项尝试 decodeURIComponentconstcountcandidates.length;for(leti0;icount;i){try{AIGenerationService.addCandidate(candidates,decodeURIComponent(candidates[i]));}catch(error){/* 忽略解码失败 */}}returncandidates;}这种候选路径策略解决了三类问题file://前缀兼容部分 API 返回带前缀的 URIfileIo.openSync需要去掉file://查询参数剥离URI 末尾的?timestampxxx等参数会导致openSync失败URL 编码还原URI 中的%20、%E4%BD%A0等编码需要解码后才能正确读取2.4 AIGenerationService 的多源读取AIGenerationService更进一步需要支持多种图片来源privatestaticasyncreadImageAsArrayBuffer(imageUri:string):PromiseArrayBuffer{if(imageUri.startsWith(data:)){returnAIGenerationService.dataUrlToArrayBuffer(imageUri);// Base64 DataURL}if(imageUri.startsWith(http://)||imageUri.startsWith(https://)){returnAIGenerationService.downloadImageAsArrayBuffer(imageUri);// 远程 URL}returnAIGenerationService.readLocalImageAsArrayBuffer(imageUri);// 本地文件}这个设计体现了多源统一处理的思想——无论图片来自本地磁盘、远程网络还是 Base64 DataURL最终都统一输出为ArrayBuffer后续的压缩和编码流程无需关心图片来源。三、图片解码ImageSource PixelMap拿到ArrayBuffer后我们需要将其解码为可操作的像素图PixelMap才能进行缩放和重新编码。privatestaticasynccompressImageBuffer(sourceBuffer:ArrayBuffer):PromiseArrayBuffer{constsource:image.ImageSourceimage.createImageSource(sourceBuffer);letpixelMap:image.PixelMap|nullnull;constpacker:image.ImagePackerimage.createImagePacker();try{constinfo:image.ImageInfoawaitsource.getImageInfo();constmaxEdgeMath.max(info.size.width,info.size.height);constsampleSizeMath.max(1,Math.ceil(maxEdge/COMPRESSED_IMAGE_MAX_EDGE));constdecodingOptions:image.DecodingOptions{sampleSize:sampleSize,// 降采样因子editable:true// 允许后续编辑Packer 需要};pixelMapawaitsource.createPixelMap(decodingOptions);// ... 后续压缩}finally{// 资源释放}}3.1 降采样Sample Size——第一级压缩这里实现了一个关键的优化点在解码阶段就缩小图片尺寸。constmaxEdgeMath.max(info.size.width,info.size.height);constsampleSizeMath.max(1,Math.ceil(maxEdge/COMPRESSED_IMAGE_MAX_EDGE));sampleSize的含义是解码时每sampleSize个像素采样 1 个像素。例如一张 4000×3000 的图片maxEdge 4000COMPRESSED_IMAGE_MAX_EDGE 1280则sampleSize ceil(4000/1280) 4。解码后的 PixelMap 分辨率变为约 1000×750——直接减少了16 倍的像素数量。这种做法的好处是减少内存占用更大的图片解码为 PixelMap 后会占用大量内存一张 4000×3000 的 RGBA 图片需要 48MB加速后续处理Packer 处理更小的 PixelMap 更快保留足够质量1280px 或 1024px 的边缘长度对 AI 服务已经足够3.2 ImageInfo 获取图片尺寸constinfo:image.ImageInfoawaitsource.getImageInfo();// info.size.width, info.size.height在解码前先获取图片信息便于动态计算合适的降采样倍数而不是写死一个固定的缩放尺寸。四、ImagePacker 编码——第二级压缩解码并缩小后的 PixelMap需要通过ImagePacker重新编码为 JPEG 格式。这是第二级——也是更精细的——压缩控制。4.1 PackingOption 配置constpackOptions:image.PackingOption{format:image/jpeg,// 输出格式quality:COMPRESSED_IMAGE_QUALITY,// JPEG 质量0-100bufferSize:TARGET_UPLOAD_IMAGE_BYTES*2// 输出缓冲区大小};参数值说明formatimage/jpegJPEG 格式支持有损压缩体积远小于 PNGquality78AI生成/68识别数值越低体积越小但画质损失越大bufferSize目标大小 × 2预分配足够大的输出缓冲区避免多次扩容选择 JPEG 而非 PNG 的原因JPEG 的有损压缩可以在相同画质下获得更小的文件体积AI API 传输时对画质损失不敏感儿童绘画线条简单JPEG 压缩伪影不明显4.2 两阶段质量降级策略项目中实现了一个先尝试不满足再降级的两阶段策略// 第一阶段用较高 quality 尝试letcompressedawaitpacker.packToData(pixelMap,packOptions);// 如果还是太大用更低 quality 重新压缩if(compressed.byteLengthTARGET_UPLOAD_IMAGE_BYTES){constsmallerOptions:image.PackingOption{format:image/jpeg,quality:62,// 从 78 降到 62AIGenerationServicebufferSize:TARGET_UPLOAD_IMAGE_BYTES*2};compressedawaitpacker.packToData(pixelMap,smallerOptions);}returncompressed;这种策略的巧妙之处在于优先保证质量第一次尝试用较高的 quality78 或 68多数图片在此阶段已达标降级有度仅当首次压缩结果仍然超标时才降级而不是一开始就用低质量无需二次解码对同一个 PixelMap 多次调用packToData无需重新解码五、util.Base64Helper 编解码压缩完成后ArrayBuffer需要编码为 Base64 字符串才能放入 HTTP 请求体中。5.1 编码ArrayBuffer → Base64privatestaticarrayBufferToBase64(buffer:ArrayBuffer):string{constbytesnewUint8Array(buffer);constbase64newutil.Base64Helper();returnbase64.encodeToStringSync(bytes);}关键步骤Uint8Array包装Base64Helper.encodeToStringSync接受Uint8Array而非ArrayBuffer需要用new Uint8Array(buffer)包装同步编码encodeToStringSync是同步方法不会阻塞 UI 线程因为编码是纯 CPU 计算耗时通常小于 10ms5.2 解码Base64 → ArrayBuffer当遇到 Base64 格式的 DataURL 时需要反向解码privatestaticdataUrlToArrayBuffer(dataUrl:string):ArrayBuffer{constcommaIndexdataUrl.indexOf(,);constbase64TextcommaIndex0?dataUrl.substring(commaIndex1):dataUrl;constbase64newutil.Base64Helper();constbytesbase64.decodeSync(base64Text);returnbytes.buffer.slice(bytes.byteOffset,bytes.byteOffsetbytes.byteLength);}这里处理了 DataURL 的data:image/jpeg;base64,前缀通过indexOf(,)定位真正的 Base64 数据起始位置。decodeSync返回Uint8Array通过.buffer属性获取底层的ArrayBuffer。5.3 Base64Helper 的编解码矩阵方法输入输出用途encodeToStringSyncUint8Arraystring图片压缩后编码用于 API 请求decodeSyncstringUint8Array解码 API 返回的 Base64 图片数据六、内存管理finally 块中的资源释放这是整个流程中最容易被忽视但也最重要的一环。HarmonyOS 的ImageSource、PixelMap、ImagePacker都是原生资源对象不遵守 ArkTS 的垃圾回收机制必须手动释放。try{// ... 解码、压缩、编码}finally{if(pixelMap!null){awaitpixelMap.release();// 释放像素图内存}awaitpacker.release();// 释放打包器awaitsource.release();// 释放图片源}6.1 释放顺序与安全性pixelMap需要判空因为它可能在createPixelMap抛出异常时为nullpacker和source在createImagePacker和createImageSource成功后始终非空释放顺序没有严格依赖但建议按创建的反序释放即使某个release()抛出异常finally块中后续的release()仍然会执行6.2 不释放的后果如果忘记调用release()每次压缩操作都会泄漏数百 KB 到数 MB 的原生内存在连续多次压缩如图生视频的轮询场景中内存会持续增长最终可能触发系统 OOMOut of Memory导致应用闪退七、两大服务的策略对比AIGenerationService和ImageRecognitionService虽然使用了相同的技术栈fileIo ImageSource ImagePacker Base64Helper但在具体参数上根据不同场景做了差异化配置对比维度AIGenerationServiceImageRecognitionService目标大小900KB520KB最大边缘1280px1024px首次 quality7868降级 quality6252读取方式支持本地/远程/DataURL 多源仅本地文件URI 候选5 种候选路径2 种file://前缀处理压缩失败处理降级使用原图 Base64降级使用原图 Base64用途上传到图生视频 API嵌入 GPT-4o-mini 请求体可以看到识别服务更加激进——更低的目标大小520KB、更小的边缘1024px、更低的质量68 再降至 52。这是因为 GPT-4o-mini 只需要理解画面内容而非关注精细的像素细节而图生视频服务需要保留足够多的视觉信息来生成流畅的动画。八、错误处理与降级策略整个图片处理链路中每一步都可能失败项目中设计了多层降级机制8.1 读取阶段的降级readImageAsArrayBuffer通过候选路径机制实现隐式降级——第一个候选路径失败后自动尝试下一个所有候选都失败才抛出异常。8.2 压缩阶段的降级prepareUploadBase64实现了显式降级try{constcompressedBufferawaitAIGenerationService.compressImageBuffer(sourceBuffer);constcompressedBase64AIGenerationService.arrayBufferToBase64(compressedBuffer);returncompressedBase64;}catch(error){// 压缩失败降级使用未压缩的原图constsourceBase64AIGenerationService.arrayBufferToBase64(sourceBuffer);returnsourceBase64;}这种压缩失败不阻断流程的设计保证了即使在极端情况下如解码异常、内存不足用户的动画生成请求也不会中断。8.3 图片过大阻断无论是读取还是压缩阶段都有 12MB 的硬性上限检查if(stat.sizeMAX_IMAGE_BYTES){// 12MBthrownewError(图片超过 12MB请压缩后再生成);}这是出于 API 请求体大小的现实考量——12MB 的原图即使压缩也很难降到合理范围不如尽早阻断并提示用户。九、完整流程图用户拍照/选择图片 │ ▼ getReadableUriCandidates(imageUri) ┌────┴────┐ │ 尝试候选路径 │──失败→ throw Error └────┬────┘ │ 成功 ▼ fileIo.openSync() → fileIo.statSync() → fileIo.readSync() → fileIo.closeSync() │ ▼ ArrayBuffer (原始图片数据) │ ▼ image.createImageSource(buffer) │ ▼ source.getImageInfo() → 计算 sampleSize │ ▼ source.createPixelMap({ sampleSize, editable: true }) ← 第一级降采样 │ ▼ packer.packToData(pixelMap, { format:jpeg, quality:78 }) ← 第二级质量压缩 │ ├── 达标 900KB→ 继续 │ └── 未达标 → packToData(quality:62) → 继续 │ ▼ arrayBufferToBase64(compressed) → Base64 字符串 │ ▼ 发送到 AI API总结本文通过画伴梦工厂两个核心服务的真实代码完整拆解了 HarmonyOS 下图片压缩与 Base64 编解码的技术方案技术点核心 API作用文件读取fileIo.openSync/statSync/readSync/closeSync将磁盘文件读入内存 ArrayBuffer候选路径getReadableUriCandidates兼容不同格式的 URI图片解码image.createImageSource→PixelMap将 ArrayBuffer 解码为可操作像素图降采样DecodingOptions.sampleSize第一级压缩缩小分辨率图片编码ImagePacker.packToData第二级压缩JPEG 质量控制两阶段降级首次 quality → 降级 quality优先保质量不达标则降级Base64 编码util.Base64Helper.encodeToStringSyncArrayBuffer → Base64 字符串Base64 解码util.Base64Helper.decodeSyncBase64 字符串 → ArrayBuffer内存管理pixelMap.release()/packer.release()/source.release()防止原生内存泄漏此套方案在项目中经受住了真实 AI API 调用的考验——单次图生视频任务中图片从可能的 510MB 压缩到 900KB 以内传输效率提升 80% 以上且 AI 生成的视频画质与使用原图几乎无差别。下一篇第 3.5 篇将介绍GPT-4o-mini 图像识别——如何通过结构化 Prompt 设计让 AI 理解儿童绘画内容并将自由文本规范化为结构化的识别结果。参考源码本文所有代码均来自项目文件products/default/src/main/ets/services/AIGenerationService.ets— 图生视频服务包含多源读取、两阶段压缩、Base64 编解码的完整实现约 900 行products/default/src/main/ets/services/ImageRecognitionService.ets— 图像识别服务包含 fileIo 流式读取、候选路径 fallback、更激进的压缩策略