把C++图像解析能力封进HarmonyOS应用时，最危险的环节往往不是JPEG有多少个标记，而是ArkTS传过来的内存究竟从哪里开始、究竟到哪里结束，以及由谁在最后释放。对一个Uint8Array，业务很容易只看byteLength，却忘了它可能只是更大ArrayBuffer的一段视图。如果Native把底层缓冲区起始地址当成当前视图起点，解析器就会读取到图像头之外的内容；反过来，若 Native 在返回前随手free(data)，还可能碰到由JS引擎管理的内存重复释放。
这一篇围绕一个极小的二进制头做问题隔离，不讨论图像超分模型、照片Exif方向推断的视觉效果，也不与前面的媒体URI授权准入相混。Demo叫NativeHeaderGate，Native文件entry/src/main/cpp/header_parser.cpp，ArkTS包装HeaderAdapter.ets，页面HeaderGatePage与BufferAuditPage。样本批次camera_headers_08，任务HDR-1010-18，测试8组，其中4组按自定义协议通过、4组因边界或格式问题拒绝，状态HEADER_GUARDED。本例以IMG_0142.bin为示意输入；底层缓冲区40B、视图偏移8B、视图长度24B、自定义头最小12B。有效头解析为宽4032、高3024、方向值6。所有数据来自固定夹具，Native调用仍标记NOT_RUN。
一、先确定解析对象：不是整个 ArrayBuffer，而是它的一扇窗
1. 借用指针不是自己分配内存
华为Node-API开发规范对Buffer归属有明确约束：通过napi_get_arraybuffer_info等接口得到的data受JS引擎管理，开发者不得自行释放。同一份规范也强调跨环境访问napi_value的风险、句柄作用域管理以及发生错误时检查napi_status。这意味着C++收到一段数组时，第一件事不该是“想办法把它转成C指针”，而应先记录它的类型、长度、偏移、来源对象和生命周期。单独将裸指针保存成全局缓存并在未来线程继续访问，会同时破坏多项前提。
本篇选择Uint8Array，不选择一般的number[]。两者在ArkTS可以保存类似的数值，却不能在Node-API里互相替代。华为的FAQ也明确指出，普通数组不能直接当ArrayBuffer交给napi_get_arraybuffer_info，而TypedArray应通过匹配的相关接口读取。对三方图像头解析器而言，这既是类型正确性问题，也是性能预算：一次无谓的大数组复制可能比解析十二个字节本身还慢。不过“减少复制”并不意味着允许使用超出视图边界的内存。
本例用一个40B底层缓冲区模拟图片片段，前8B代表无关前缀，随后24B是本次传给Native的视图。解析器应该看到的是从视图位置0开始的头，不是ArrayBuffer偏移0。自定义头以ASCIIE、X两个字节作为测试魔数，第三字节是协议版本1，第四字节是方向值6，再用两个小端32位无符号整数表示宽4032和高3024。这里的“方向6”借用了图片领域熟悉的编号，但这个12B格式纯属本文夹具格式，不是标准EXIF、JPEG APP1结构或任何第三方库真正承诺的数据格式。
2. 从最短头到最大合法视图
校验顺序要先于读取顺序。类型是否为Uint8Array、视图是否处于底层缓冲区范围内、长度是否达到12B，是读取第一个字段前的门槛。之后才能校验魔数、版本、方向枚举和宽高上限。举例说，若长度只有8B，就不应该先读宽和高再报告SHORT_HEADER；否则崩溃时根本没有可追溯的错误码。宽高虽然不涉及申请图像像素内存，也要限定有效值范围，防止不可信元数据在后续被误用来规划超大解码缓冲区。
关于视图偏移，常见的双重偏移错误尤其隐蔽：napi_get_typedarray_info返回的data已经代表当前TypedArray视图的数据起始地址。如果Native再手工给这个地址加一次byteOffset，就会跳过正确头，甚至越界。byteOffset的用途在这里是核对“视图确实被包含在底层ArrayBuffer内”，而不是再次做指针加法。规范示例中还有一个重要细节：TypedArray返回的length按元素数量计数；只有对Uint8Array，元素数才等于字节数。换成Float32Array时按原样作为字节数会低估或错估边界。
二、把“是不是能读”放在“读到了什么”前面
下面的C++片段只演示Native侧的边界与头字段校验。它假定模块加载注册代码已经单独按照官方工程模板接好，并且函数在正常的Node-API调用线程执行。示例刻意检查每一步返回状态，失败就抛出范围或类型错误；它不会调用第三方JPEG解析器，也不会把数据保存到异步任务或全局指针中。实际部署前仍需依据工程SDK头文件、ABI和编译器作编译测试。
#include<napi/native_api.h>#include<cstdint>#include<cstddef>staticuint32_tReadU32LE(constuint8_t*p){returnstatic_cast<uint32_t>(p[0])|(static_cast<uint32_t>(p[1])<<8)|(static_cast<uint32_t>(p[2])<<16)|(static_cast<uint32_t>(p[3])<<24);}staticnapi_valueParseHeader(napi_env env,napi_callback_info info){size_t argc=1;napi_value args[1]={nullptr};if(napi_get_cb_info(env,info,&argc,args,nullptr,nullptr)!=napi_ok||argc!=1){napi_throw_type_error(env,nullptr,"Uint8Array required");returnnullptr;}boolisTyped=false;if(napi_is_typedarray(env,args[0],&isTyped)!=napi_ok||!isTyped){napi_throw_type_error(env,nullptr,"TypedArray required");returnnullptr;}napi_typedarray_type type;size_t elementCount=0;void*viewData=nullptr;napi_value arrayBuffer=nullptr;size_t byteOffset=0;if(napi_get_typedarray_info(env,args[0],&type,&elementCount,&viewData,&arrayBuffer,&byteOffset)!=napi_ok||type!=napi_uint8_array){napi_throw_type_error(env,nullptr,"Uint8Array only");returnnullptr;}void*baseData=nullptr;size_t baseLength=0;if(napi_get_arraybuffer_info(env,arrayBuffer,&baseData,&baseLength)!=napi_ok||byteOffset>baseLength||elementCount>baseLength-byteOffset||viewData==nullptr){napi_throw_range_error(env,nullptr,"VIEW_OUT_OF_BOUNDS");returnnullptr;}// viewData 已位于视图首字节，不得再加 byteOffset，更不得 free(viewData)。if(elementCount<12){napi_throw_range_error(env,nullptr,"SHORT_HEADER");returnnullptr;}constauto*p=static_cast<constuint8_t*>(viewData);if(p[0]!=0x45||p[1]!=0x58){napi_throw_type_error(env,nullptr,"BAD_MAGIC");returnnullptr;}if(p[2]!=1){napi_throw_range_error(env,nullptr,"UNSUPPORTED_VERSION");returnnullptr;}uint32_twidth=ReadU32LE(p+4);uint32_theight=ReadU32LE(p+8);if(width==0||height==0||width>16384||height>16384||p[3]<1||p[3]>8){napi_throw_range_error(env,nullptr,"INVALID_DIMENSIONS_OR_ORIENTATION");returnnullptr;}napi_value result=nullptr,w=nullptr,h=nullptr,orientation=nullptr;if(napi_create_object(env,&result)!=napi_ok||napi_create_uint32(env,width,&w)!=napi_ok||napi_create_uint32(env,height,&h)!=napi_ok||napi_create_uint32(env,p[3],&orientation)!=napi_ok)returnnullptr;napi_set_named_property(env,result,"width",w);napi_set_named_property(env,result,"height",h);napi_set_named_property(env,result,"orientation",orientation);returnresult;}这段代码没有创建任何需要业务端free的Native堆对象。viewData和baseData都是借用指针，函数返回后不再使用；napi_value返回对象由JS引擎管理。若调用方确需跨回调保留缓冲区，应该通过规范的引用管理让相应JS对象存活，并明确线程归属和释放时机，而不是只持有裸地址。这里没有写napi_remove_wrap，因为本例没有使用napi_wrap；不能为显示“会释放”而胡乱加入不相关API。
还必须提醒：代码里抛错本身不等于业务日志已经完整。生产实现应把错误码映射为稳定的应用分类并记录安全的参数摘要，例如输入字节数、偏移、格式版本，而不要把原始二进制数据打印到HiLog。真实照片可能包含敏感元数据，在错误链路上将原始头字节完整打印出来会引入新的隐私风险。示例页只展示经过脱敏的文件名IMG_0142.bin和固定参数。
三、ArkTS 一侧也要对输入形态负责
Native的防御不是让ArkTS随意构造坏输入的许可证。在跨语言入口前统一将字节流表示为Uint8Array，可避免第三方工具返回number[]、DataView、Uint8ClampedArray造成隐式转换。转换需要明确是复制还是视图，不能默认二者等价。下面代码构造示意性的40B缓冲区，前8B留空，在视图起点写入12B协议头。它不从相册读取任何照片，也不去访问文件系统。Native模块调用被显式屏蔽，以保证读者不会把演练结果误解为已加载SO。
interfaceHeaderModel{width:number;height:number;orientation:number;}functionmakeFixture():Uint8Array{constowner:ArrayBuffer=newArrayBuffer(40);constview:Uint8Array=newUint8Array(owner,8,24);// 自定义12字节头：'EX'、版本1、方向6、宽4032、高3024。constheader:number[]=[0x45,0x58,0x01,0x06,0xC0,0x0F,0x00,0x00,0xD0,0x0B,0x00,0x00];for(leti=0;i<header.length;i++)view[i]=header[i];returnview;}functiondecodeFixture(view:Uint8Array):HeaderModel{if(view.length<12)thrownewError('SHORT_HEADER');if(view[0]!==0x45||view[1]!==0x58)thrownewError('BAD_MAGIC');if(view[2]!==1)thrownewError('UNSUPPORTED_VERSION');constwidth=(view[4]|(view[5]<<8)|(view[6]<<16)|(view[7]<<24))>>>0;constheight=(view[8]|(view[9]<<8)|(view[10]<<16)|(view[11]<<24))>>>0;return{width,height,orientation:view[3]};}constbytes:Uint8Array=makeFixture();constresult:HeaderModel=decodeFixture(bytes);// 4032 × 3024, orientation=6// Native正式接入示例：nativeheader.parseHeader(bytes)，此处 NOT_RUN。这里最值得保留的一行不是result.width，而是new Uint8Array(owner, 8, 24)：它明确产生一个有起始偏移的视图，强迫Native面对“实际数据不是从底层缓冲区0开始”的边界。测试如果只构造new Uint8Array(12)，大部分二次偏移错误都不会被发现。同时不要在C++访问过程中修改原来的JS缓冲区，尤其是涉及Worker和多线程共享时；如果业务必须允许并发写入，应先复制稳定快照或设计受控的同步协议。
应用展示层也要区别“检查样例成功”和“Native解析器已经编译通过”。本轮的业务结果称为HEADER_GUARDED，意味着我们在固定输入模型中识别了对应的非法头，不是系统安全认证。只有nativeInvocation=NOT_RUN时，才不会把生成的IDE画面当作实测证据。若真实接入成功，日志应当额外包含ABI、目标设备类型、so版本及官方SDK环境，但这些内容不能被本篇模拟结果冒充。
四、用八组输入说明四种拒绝的来路
固定批次camera_headers_08把拒绝原因拆为SHORT_HEADER、BAD_MAGIC、UNSUPPORTED_VERSION和VIEW_OUT_OF_BOUNDS，每种各一条；另有四条满足本地头格式的有效样例。这里需澄清一个很容易让教程失真的边界：正常由JavaScript构造的Uint8Array本身不可能拥有越过其底层ArrayBuffer末尾的合法视图，因为运行时在构造时就会拒绝。VIEW_OUT_OF_BOUNDS这组是模拟被破坏的外部视图描述符，用于验证边界逻辑本身；它不是声称真正创建出了越界TypedArray实例。Native中再次检查偏移与总长是防御性编程，不表示运行时常常会返回错误结构。
短头拒绝必须发生在任何宽高读取之前；错误魔数应在最小长度通过之后识别；不支持的版本应在认定字段布局稳定之前阻断。这些原因不能被统一写成“解析失败”，否则第三方适配升级时看不出是协议兼容、数据损坏，还是调用方传入了错误类型。样例日志记录cases=8 accepted=4 rejected=4，具体原因4类各1，内存归属为JS_ENGINE，borrowedPointersStored=0、manualFree=false。这些值之间形成互相约束：如果拒绝是4，就不能只列3条原因；如果宣称没有保存借用指针，就不能在页面离开之后继续读取先前保存的地址。
在工程中，返回结果的业务结构还应携带实际传入的文件版本、来源标识、解析器版本和校验摘要，供上层判断是否允许开启后续解码。因为本文只读12B头，绝对不能因头校验通过便推论文件整体没有恶意载荷、图片格式完整、解码器安全或EXIF语义正确。最小头校验只是入口门槛，完整文件解析还依赖专业解析库及其安全更新策略。必要时要把Native逻辑放入受限制的处理链路，设定最大输入尺寸和资源配额。
主页面显示的是一个可以人工审计的固定输入：HDR-1010-18、40B底层缓冲区、偏移8B、视图长度24B、最小头12B、样例宽4032与高3024、方向6、8组用例中的4通过4拒绝。画面中任何看起来像“真实图片解码成功”的文字都应被当成演示语义，而不是真实文件读取结果。我们不把这些头字段导向图片内容展示，只将它们作为格式校验后的数值元信息。比起画一个漂亮的解码前后效果图，这类界面更能让读者知道本篇确实只处理二进制边界。
五、资源生命周期：不做错误的释放比多写释放函数重要
工程代码常见一种表面上的整洁：每个函数末尾都调用一次delete或free，仿佛这样就一定不会内存泄漏。Node-API里恰好相反：借来的ArrayBuffer内存根本不归Native释放。napi_get_arraybuffer_info和napi_get_typedarray_info的返回指针受JS引擎管理，Native只可在合法调用及有效对象生命周期内使用。错误地执行delete[] data即使在某个测试环境里没有立刻崩溃，也是在破坏所有权契约。应该释放的是自己通过malloc、new或第三方库明确创建的资源，而不是在回调里见到的每一个指针。
对输出对象也一样，返回napi_value不代表C++必须自己分配和销毁它。运行时创建的对象应由正确的句柄作用域和引用机制管理。如果三方库返回一个需要显式释放的上下文对象，应在适配层封装RAII或配套的releaseContext，并保证异常路径也执行清理；如果使用napi_wrap与napi_ref，则按官方规范管理引用和最终清理时机。明确谁拥有资源是两边对接前必须回答的问题，否则“如何释放”根本无从讨论。
此外，Native中缓存napi_env给其他线程也是高风险做法。文档强调不同环境内的JS对象不能交叉使用，某个环境析构后继续访问更可能导致崩溃。若要做长时间的图像处理，应考虑受支持的异步工作模式，把必要字节复制到Native自己持有的缓冲区，任务结束释放复制品，并用正确的线程安全方式把结果送回ArkTS。这个拷贝虽有成本，却能建立清晰的生命线；不是所有“零拷贝”都比安全更重要。
六、诊断图应该回答“这一次究竟拒绝了什么”
诊断页BufferAuditPage将八条样本的裁决展开。前四条是有效头；第五条因短于12B拒绝；第六条魔数不是EX；第七条版本不等于1；第八条是外部描述符模拟越界。页面只展示行号、错误类别、视图结构和归属，不写原始可能含隐私的图片路径。这样即使被业务负责人截成问题报告，也能说清楚风险来自哪条边界，而不是只留下一个红色的FAILED。
如果真正运行C++版本，错误信息还应关联Native库构建标识、输入字节的非敏感摘要和设备系统能力；建议不要把原始缓冲区地址作为业务日志长期保留。指针数值可能帮助一次本地调试，但在跨进程、跨线程、跨设备记录中既不稳定，也无业务意义。错误码则应尽量稳定，避免同一类越界在不同代码路径被映射成两个名称。需要复盘时，先用本地最小夹具重放，再拿真实脱敏数据扩大覆盖面。
本轮诊断只保证固定模型的结果，未能证明Native SO已链接、实际napi_get_typedarray_info已被调用或存在可利用的越界漏洞。示意页面顶部写的是HEADER_GUARDED，底部同时写nativeInvocation=NOT_RUN，这两个字段不矛盾：前者是应用模型状态，后者是平台执行证据。若团队把两者合并为“安全通过”，上线验收会形成非常严重的盲区。
七、如何把固定样例升级成真实的工程验收
首先应在DevEco中建立正确的Native模块工程，核对module.json5与CMake配置、so模块名及入口函数的实际匹配关系。其次通过ArkTS真实传入带偏移的Uint8Array，在Native读取元素数量、偏移、底层长度和内存起点，确认不会重复偏移。随后分别做空输入、12B边界、较大合法长度、不同TypedArray类型、异常版本和连续多次调用。对异常输入要观察是否仅抛出可控错误，而非应用进程崩溃。全部测试都需要同时检查Native侧资源管理和页面返回后的对象引用情况。
接入真正三方解析器时，首先弄清它是否复制了数据，还是异步保留了调用者指针。同步只读函数与异步图像库对调用方内存的所有权要求完全不同。若接口要求输入在任务结束前稳定，就不能把一个临时借用指针扔进后台线程；应显式复制或延长JS对象引用寿命，且要核对跨线程使用限制。即使实现正确，也要在低内存、页面快速关闭、进程重启、多核竞争时做专项测试，才能谈“没有泄漏”和“不会越界”。
再往产品层走，图像头只完成基础元数据准入。后续的解码像素预算、方向变换、图像大小限制、恶意文件检测与个人信息处理都需要独立的状态约束。上一轮的Image Kit方向门禁属于另一个工程环节，本篇没有把这些内容重复造一遍；我们把时间花在一个更靠下层、可复用到三方EXIF库、色彩解析库和图像容器插件的借用内存协议上。多个阶段各自承认未验证的部分，远比一张“大功告成”海报有用。
如果团队把这段逻辑封装成共享三方库，还应当固定一个兼容性表：库的版本、支持的输入视图类型、协议头版本、大小端策略、最大字段尺寸以及失败码之间要有一一对应的解释。升级底层库时，不能只凭“正常照片能解析”便认为二进制入口向后兼容；应让同一批固定头、缩短视图、错位视图和错误版本在新旧库上运行，比较是否出现新的拒绝或不受控异常。针对高风险位置可开启编译器和运行时支持的内存诊断手段，但这些工具的可用性依赖实际NDK、签名和运行环境，不能把未执行的工具报告当作结论。尤其重要的是，异常分支必须与成功分支共用资源清理契约，否则压力测试越充分，隐藏的生命周期缺陷越容易暴露。
八、留下能被另一个开发者继续追查的边界
最终交付物的固定输入结论是8例中4例通过、4例拒绝，样例IMG_0142.bin的宽高和方向可由12B自定义头重现；40B底层Buffer中只向解析器暴露从第8B开始的24B视图；Native不得再加一次偏移，也不得释放引擎持有的内存。这几个判断都是通过Node-API接口契约和本地模型演练可以解释的规则，而不是从真实设备截图逆向猜测出来的成功故事。
读完以后更值得问的问题是：如果某个三方库在回调后仍保留了data，谁来延长生命周期？如果运行时传进来的是普通JS数组，能否明确拒绝而不是隐式解释？如果把Uint8Array换成Float32Array，长度单位是不是还一致？如果用户在页面离开时取消任务，有没有异步对象继续读取那块内存？这些问题能够自然形成下一轮真正的Native适配工作，也能帮助代码审查从接口使用转向资源归属。
参考资料：华为 Node-API开发规范（2026-07-28）；华为 C++侧ArrayBuffer接收Float数组FAQ（2026-06-26）；华为Node-API简介。
