【开源软件移植】鸿蒙 PC 三方库适配实战从 7-Zip Native 编译到 ArkTS 调用完整跑通一、写在前面欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/这篇文章记录的是把 7-Zip 的.7z压缩、校验、解压能力适配成 HarmonyOS / OpenHarmony PC 可复用三方库的完整过程。sevenzip-ohos不是把一个前端页面塞进 HAP也不是处理静态资源路径而是一次完整的 Native 三方库适配固定 7-Zip 上游源码版本裁剪 reduced 版.7z能力用 CMake 交叉编译鸿蒙 Native.so通过 Node-API 暴露给 ArkTS打成 HAR / OHPM 可复用库写一个entryDemo 在鸿蒙 PC 真机上完成压缩、测试、解压烟测最终实测结果如下compress: oktrue, code0, messageEverything is Ok test: oktrue, code0, messageEverything is Ok extract: oktrue, code0, messageEverything is Ok也就是说这条链路已经在鸿蒙 PC 设备上跑通ArkTS Demo - HAR Library - libsevenzip_napi.so - Node-API - C bridge - 7-Zip 26.01 reduced core - 应用沙箱文件系统本文不会把它包装成“很简单”。7z 适配真正麻烦的地方不在按钮页面而在 Native 编译、7-Zip 内部静态注册机制、NAPI 异步任务、签名安装、SDK 环境和文件权限。本文按实战踩坑顺序展开尽量让下一次复现少走弯路。本项目开源仓库https://atomgit.com/weixin_52908342/sevenzip-ohos二、适配目标和边界本次适配目标是做一个可被 ArkTS 项目引用的 7z 三方库而不是做一个完整的压缩软件。首版边界如下只支持.7z格式使用 7-Zip reduced 版源码不引入 RAR支持压缩、解压、归档测试支持密码参数预留只验证应用沙箱路径首版串行执行任务不承诺多任务并发不引入汇编优化不改 7-Zip 上游源码只新增 bridge、NAPI、工程配置为什么不直接把7zr可执行文件塞进应用里因为三方库更适合走.so ArkTS wrapper d.ts的形态。子进程调用可执行文件会带来路径、权限、进度回调、错误码和 ABI 分发问题同进程 Native 库更符合鸿蒙三方库交付方式。最终方案是7-Zip 26.01 源码 - CMake 编译为 Native 对象 - libsevenzip_napi.so - ArkTS Promise API - HAR / OHPM 引用三、环境信息本次实战环境如下系统Windows IDEDevEco Studio SDKHarmonyOS 6.0.0 Beta3 / API 20 目标设备鸿蒙 PC Native ABIarm64-v8a 7-Zip 源码ip7z/7zip tag 26.01项目路径示例C:\Users\24190\Desktop\Harmony\sevenzip-ohosDevEco Studio 中 SDK 路径要注意。实战中如果把 SDK 指到default层级可能出现00303168 Configuration Error SDK component missing.命令行或 IDE 中建议 SDK 根路径使用E:\DevEco Studio\sdk而不是E:\DevEco Studio\sdk\default命令行构建时还需要补上 DevEco 自带 JBR$env:DEVECO_SDK_HOMEE:\DevEco Studio\sdk$env:JAVA_HOMEE:\DevEco Studio\jbr$env:PATHE:\DevEco Studio\jbr\bin;$env:PATH四、工程结构适配完成后的工程结构如下sevenzip-ohos/ ├── AppScope/ │ ├── app.json5 │ └── resources/ ├── entry/ # 真机烟测 Demo │ ├── build-profile.json5 │ ├── oh-package.json5 │ └── src/main/ │ ├── module.json5 │ ├── ets/ │ │ ├── entryability/ │ │ └── pages/Index.ets │ └── resources/ ├── library/ # 可复用 HAR 三方库 │ ├── build-profile.json5 │ ├── oh-package.json5 │ └── src/main/ │ ├── module.json5 │ ├── ets/ │ │ ├── Index.ets │ │ └── types/SevenZipOptions.ets │ └── cpp/ │ ├── CMakeLists.txt │ ├── sevenzip_sources.cmake │ ├── include/sevenzip_ohos.h │ ├── bridge/sevenzip_command_bridge.cpp │ ├── bridge/sevenzip_command_bridge.h │ ├── napi/sevenzip_napi.cpp │ ├── types/libsevenzip_napi/index.d.ts │ └── third_party/7zip/ ├── scripts/ │ ├── gen-sevenzip-sources.cjs │ └── verify-sevenzip-sources.cjs ├── NOTICE └── README.md其中library是真正要交付的三方库entry只是为了在鸿蒙 PC 上跑烟测。五、创建鸿蒙工程和 Library 模块先创建普通 ArkTS Stage 工程然后新增一个 Library 模块模块名建议使用librarylibrary/oh-package.json5中配置三方库包名{ name: your-scope/sevenzip-ohos, version: 0.1.0, description: 7z archive compression library for OpenHarmony / HarmonyOS PC., main: src/main/ets/Index.ets, types: src/main/cpp/types/libsevenzip_napi/index.d.ts, license: LGPL-2.1-or-later, dependencies: {} }entry/oh-package.json5中引用本地 Library{ name: entry, version: 0.1.0, dependencies: { your-scope/sevenzip-ohos: file:../library } }项目级build-profile.json5要同时声明两个模块{ modules: [ { name: entry, srcPath: ./entry }, { name: library, srcPath: ./library } ] }实战中如果忘了给AppScope/app.json5加图标会直接在 PreBuild 阶段失败must have required property icon需要补{ app: { bundleName: com.example.sevenzipohos, vendor: example, versionCode: 1000000, versionName: 0.1.0, label: $string:app_name, icon: $media:app_icon } }entry/src/main/module.json5中也要给 Ability 补启动窗口资源{ abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, label: $string:EntryAbility_label, icon: $media:app_icon, startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background, exported: true } ] }否则会报must have required property startWindowIcon must have required property startWindowBackground截图占位DevEco Studio 工程目录展示entry和library两个模块。六、引入 7-Zip 源码本次固定使用官方ip7z/7zip仓库 taggitclone--depth1--branch26.01https://github.com/ip7z/7zip.git library/src/main/cpp/third_party/7zip实际记录版本tag: 26.01 commit: 8c63d71ff886bda90c86db28466287f977374237和本次适配关系最紧密的是CPP/7zip/Bundles/Alone7z/makefile.gcc这个 makefile 对应7zrreduced 版只处理 7z 格式正好适合作为三方库首版基线。注意不要直接把整个 7-Zip 工程无脑编进去。首版不需要RARGUIWindows resource汇编优化外部 codec 插件七、生成 CMake 源文件清单7-Zip reduced 版依赖的 C/C 文件很多手写源文件清单非常容易漏。因此工程中增加脚本scripts/gen-sevenzip-sources.cjs核心思路是从官方Alone7z/makefile.gcc读取对象文件分组再映射到真实源码路径生成library/src/main/cpp/sevenzip_sources.cmake生成命令nodescripts/gen-sevenzip-sources.cjs实战中基于 7-Zip 26.01 生成了 158 个源码文件。这里要排除两个内容MainAr.cpp resource.rc原因是MainAr.cpp里有 console 程序入口main()三方库最终是.so不能带独立可执行程序入口resource.rc是 Windows resource鸿蒙 Native 不需要生成后可以再跑校验脚本nodescripts/verify-sevenzip-sources.cjs目标是确认MainAr.cpp没进 CMake 清单并且7zRegister.cpp、LzmaRegister.cpp这类注册文件都在。八、Native C ABI 设计Native 层对外不暴露 7-Zip 内部类型而是提供一个稳定的 C ABI#pragmaonce#ifdef__cplusplusexternC{#endiftypedefenumSevenZipResultCode{SEVENZIP_OK0,SEVENZIP_WARNING1,SEVENZIP_FATAL_ERROR2,SEVENZIP_USER_ERROR7,SEVENZIP_MEMORY_ERROR8,SEVENZIP_NATIVE_ERROR1000}SevenZipResultCode;typedefstructSevenZipOptions{intlevel;intthreads;intsolid;constchar*password;}SevenZipOptions;intSevenZip_Compress(constchar*archivePath,constchar**inputPaths,intinputCount,constSevenZipOptions*options);intSevenZip_Extract(constchar*archivePath,constchar*outputDir,constchar*password);intSevenZip_Test(constchar*archivePath,constchar*password);constchar*SevenZip_GetLastError();#ifdef__cplusplus}#endif这样做有两个好处ArkTS / NAPI 不依赖 7-Zip 内部 COM-like 类型后续如果把 console bridge 换成更底层 archive API对外接口可以保持稳定九、Command bridge把 7zr 命令变成库函数7-Zip 的UI/Console/Main.cpp中提供了intMain2(intnumArgs,char*args[]);所以 bridge 层做的事情是把 C ABI 参数转成7zr风格命令压缩7zr a-t7z-mx1-msoff-yarchive.7z input.txt测试7zr t archive.7z-y解压7zr x archive.7z-ooutput_dir-ybridge 层必须自己定义 7-Zip console 使用的全局 streamexternCStdOutStream g_StdOut;externCStdOutStream g_StdErr;CStdOutStream*g_StdStreamnullptr;CStdOutStream*g_ErrStreamnullptr;并且要加互斥锁std::mutex g_sevenZipMutex;原因是 7-Zip console 路径有全局状态。首版如果让多个压缩任务并发进入Main2风险很高。实战中还遇到一个编译错误error: unknown type name CMessagePathException解决方式是在 bridge 中引入#includeCPP/7zip/UI/Common/EnumDirItems.h此外还需要把 7-Zip 的异常收口到SevenZip_GetLastError()否则页面只能看到Native bridge error调试时增加了这些捕获catch(constCNewException)catch(constCMessagePathException)catch(constCSystemException)catch(NExitCode::EEnum exitCode)catch(constUStringmessage)catch(constAStringmessage)catch(constchar*message)catch(constwchar_t*message)catch(intvalue)catch(conststd::exceptionerror)catch(...)这个改动非常关键。没有它Native 层报错很难定位。十、CMake 最关键的一处必须使用 OBJECT library最开始 CMake 写法是add_library(sevenzip_core STATIC ${SEVENZIP_SOURCES}) add_library(sevenzip_napi SHARED bridge/sevenzip_command_bridge.cpp napi/sevenzip_napi.cpp ) target_link_libraries(sevenzip_napi PRIVATE sevenzip_core libace_napi.z.so libhilog_ndk.z.so )这能编译但真机运行压缩时报compress: okfalse, code2, messageUnsupported archive type这个问题很隐蔽。原因不是-t7z写错也不是.7z后缀错而是 7-Zip 的归档格式和 codec 依赖静态对象构造注册7zRegister.cpp LzmaRegister.cpp BcjRegister.cpp CopyRegister.cpp ...这些对象文件如果先被打进静态库再由.so链接器按需拉取可能因为没有显式符号引用而被丢掉。结果就是CCodecs::Formats里没有7z格式ParseOpenTypes(*codecs, 7z, types)失败最终抛出Unsupported archive type修复方式是把sevenzip_core改成 OBJECT library强制把所有 7-Zip 对象文件并入libsevenzip_napi.socmake_minimum_required(VERSION 3.16) project(sevenzip_ohos) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_C_STANDARD 99) set(CMAKE_C_STANDARD_REQUIRED ON) set(SEVENZIP_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/third_party/7zip) include(${CMAKE_CURRENT_SOURCE_DIR}/sevenzip_sources.cmake) add_library(sevenzip_core OBJECT ${SEVENZIP_SOURCES}) target_include_directories(sevenzip_core PUBLIC ${SEVENZIP_ROOT} ${SEVENZIP_ROOT}/C ${SEVENZIP_ROOT}/CPP ${SEVENZIP_ROOT}/CPP/Common ${SEVENZIP_ROOT}/CPP/Windows ${SEVENZIP_ROOT}/CPP/7zip ) target_compile_definitions(sevenzip_core PUBLIC Z7_PROG_VARIANT_R Z7_ST _FILE_OFFSET_BITS64 _LARGEFILE_SOURCE ) target_compile_options(sevenzip_core PRIVATE -fPIC -Wno-unused-parameter -Wno-sign-compare -Wno-unused-variable -Wno-missing-field-initializers ) add_library(sevenzip_napi SHARED $TARGET_OBJECTS:sevenzip_core bridge/sevenzip_command_bridge.cpp napi/sevenzip_napi.cpp ) target_include_directories(sevenzip_napi PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include ${SEVENZIP_ROOT} ${SEVENZIP_ROOT}/C ${SEVENZIP_ROOT}/CPP ) target_link_libraries(sevenzip_napi PRIVATE libace_napi.z.so libhilog_ndk.z.so )这是本次适配最关键的坑。十一、NAPI 封装Native 模块名、CMake target、ArkTS import 需要保持一致CMake target: sevenzip_napi 生成文件: libsevenzip_napi.so NAPI nm_modname: sevenzip_napi ArkTS import: libsevenzip_napi.soNAPI 层对外暴露三个 Promise APIcompress(archivePath:string,inputPaths:string[],options?:CompressOptions):PromiseSevenZipResultextract(archivePath:string,outputDir:string,password?:string):PromiseSevenZipResulttest(archivePath:string,password?:string):PromiseSevenZipResult返回结构统一为exportinterfaceSevenZipResult{code:number;ok:boolean;message:string;}错误码映射0 - 成功 1 - 警告 2 - 致命错误 7 - 命令参数错误 8 - 内存错误 1000 - Native bridge 未捕获错误压缩、测试、解压都是耗时任务所以 NAPI 层使用 async worknapi_create_async_work(...)napi_queue_async_work(...)这样 ArkTS 侧拿到的是 Promise不会长时间阻塞 UI 线程。十二、ArkTS 三方库包装library/src/main/ets/Index.ets对 Native 模块做轻包装importsevenzipNativefromlibsevenzip_napi.so;import{CompressOptions,SevenZipResult}from./types/SevenZipOptions;export{CompressOptions,SevenZipResult}from./types/SevenZipOptions;exportfunctioncompress(archivePath:string,inputPaths:string[],options:CompressOptions{}):PromiseSevenZipResult{returnsevenzipNative.compress(archivePath,inputPaths,options);}exportfunctionextract(archivePath:string,outputDir:string,password:string):PromiseSevenZipResult{returnsevenzipNative.extract(archivePath,outputDir,password);}exportfunctiontest(archivePath:string,password:string):PromiseSevenZipResult{returnsevenzipNative.test(archivePath,password);}业务项目引用时只需要import{compress,extract,test}fromyour-scope/sevenzip-ohos;Native.so类型声明放在library/src/main/cpp/types/libsevenzip_napi/index.d.tslibrary/oh-package.json5中的types必须指向.d.ts文件否则会有警告The value of types must be a .d.ts or .d.ets file.十三、Demo 烟测页面entry模块不是三方库的一部分只用于验证。页面点击按钮后执行下面流程获取应用沙箱目录context.filesDir创建输入目录sevenzip-input写入测试文件hello.txt压缩为sevenzip-smoke.7z调用test校验归档解压到sevenzip-output将每一步结果显示到页面关键路径示例base: /data/storage/el2/base/haps/entry/files input: /data/storage/el2/base/haps/entry/files/sevenzip-input/hello.txt archive: /data/storage/el2/base/haps/entry/files/sevenzip-smoke.7z output: /data/storage/el2/base/haps/entry/files/sevenzip-outputDemo 页面输出compress: oktrue, code0, messageEverything is Ok test: oktrue, code0, messageEverything is Ok extract: oktrue, code0, messageEverything is Ok十四、构建和安装14.1 DevEco Studio 运行设备连接后DevEco 顶部设备栏选择鸿蒙 PC 设备然后点运行。如果安装时报Install Failed: error: failed to install bundle. error: no signature file.说明装的是 unsigned HAP需要打开签名配置。DevEco Studio 中进入File / Project Structure / Signing Configs或者点击报错里的Open signing configs开启自动签名后重新运行。14.2 命令行构建PowerShell 中可以这样构建$env:DEVECO_SDK_HOMEE:\DevEco Studio\sdk$env:JAVA_HOMEE:\DevEco Studio\jbr$env:PATHE:\DevEco Studio\jbr\bin;$env:PATH E:\DevEco Studio\tools\node\node.exeE:\DevEco Studio\tools\hvigor\bin\hvigorw.js--mode module -p moduleentrydefault -p productdefault -p requiredDeviceType2in1 assembleHap --analyzenormal --parallel--incremental --daemon构建成功后产物位于entry/build/default/outputs/default/entry-default-signed.hap14.3 命令行安装和启动先查看设备E:\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exelist targets卸载旧包E:\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exeshell bm uninstall-n com.example.sevenzipohos注意新版本bm uninstall必须带-nbm uninstall -n bundle-name安装新包$hdcE:\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe$hapC:\Users\24190\Desktop\Harmony\sevenzip-ohos\entry\build\default\outputs\default\entry-default-signed.hap$tmpdata/local/tmp/sevenzip-ohos-install$hdcshellrm-rf$tmp$hdcshell mkdir$tmp$hdcfile send$hap$tmp$hdcshell bm install-p$tmp$hdcshellrm-rf$tmp启动应用E:\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exeshell aastart-a EntryAbility-b com.example.sevenzipohos成功输出install bundle successfully. start ability successfully.十五、实战问题和解决15.1app.json5缺少 icon报错Schema validate failed missingProperty: icon解决icon: $media:app_icon同时在AppScope/resources/base/media下放app_icon.svg。15.2 Ability 缺少启动窗口资源报错missingProperty: startWindowIcon missingProperty: startWindowBackground解决startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background15.3 安装失败no signature file报错Install Failed: error: failed to install bundle. error: no signature file.原因是 IDE 尝试安装 unsigned HAP。解决打开 Signing Configs配置自动签名重新构建 signed HAP15.4CMessagePathException未定义报错error: unknown type name CMessagePathException解决#includeCPP/7zip/UI/Common/EnumDirItems.h15.5 页面只显示Native bridge error初版 bridge 只做了catch(...){returnSEVENZIP_NATIVE_ERROR;}这会导致 ArkTS 侧完全不知道 7-Zip 内部抛了什么。解决方式增加SevenZip_GetLastError()bridge 中捕获 7-Zip 常见异常类型NAPI async work 完成时把错误信息带回 ArkTS修复后页面能显示messageUnsupported archive type这才定位到真正问题。15.6SDK component missing报错00303168 Configuration Error SDK component missing.实战中原因是 SDK 路径和 Hvigor daemon 缓存不一致。处理方式E:\DevEco Studio\tools\node\node.exeE:\DevEco Studio\tools\hvigor\bin\hvigorw.js--stop-daemon并确保$env:DEVECO_SDK_HOMEE:\DevEco Studio\sdk如果仍然失败可以清理生成缓存.hvigor entry/build library/build library/.cxx15.7Unsupported archive type报错compress: okfalse, code2, messageUnsupported archive type这是本次最关键的问题。原因是sevenzip_core用STATIC静态库时7-Zip 的静态注册对象可能被链接器丢弃导致运行时没有注册7zarchive handler。解决add_library(sevenzip_core OBJECT ${SEVENZIP_SOURCES}) add_library(sevenzip_napi SHARED $TARGET_OBJECTS:sevenzip_core bridge/sevenzip_command_bridge.cpp napi/sevenzip_napi.cpp )修复后重新构建、安装再运行烟测压缩成功。十六、最终验证结果最终在鸿蒙 PC 上完成了沙箱内烟测。页面显示build: diag-2026-05-20-2205 base: /data/storage/el2/base/haps/entry/files input: /data/storage/el2/base/haps/entry/files/sevenzip-input/hello.txt archive: /data/storage/el2/base/haps/entry/files/sevenzip-smoke.7z output: /data/storage/el2/base/haps/entry/files/sevenzip-output compress: oktrue, code0, messageEverything is Ok test: oktrue, code0, messageEverything is Ok extract: oktrue, code0, messageEverything is Ok这说明libsevenzip_napi.so能被 ArkTS 正确加载NAPI Promise 调用链路正常7-Zip reduced core 能识别并创建.7z应用沙箱路径可读写压缩成功归档测试成功解压成功十七、复现步骤汇总完整复现可以按下面顺序走创建 ArkTS Stage 工程新增libraryHAR 模块新增entryDemo 模块配置AppScope/app.json5的icon配置entry/module.json5的startWindowIcon和startWindowBackground在library/src/main/cpp/third_party引入 7-Zip 26.01 源码从Alone7z/makefile.gcc生成sevenzip_sources.cmake排除MainAr.cpp和resource.rc编写sevenzip_ohos.h编写 command bridge调用Main2编写 NAPI async workArkTS 包装compress、extract、testCMake 使用 OBJECT library 合入 7-Zip 对象文件Demo 中使用context.filesDir做沙箱路径烟测配置签名构建 signed HAP安装到鸿蒙 PC点击按钮验证压缩、测试、解压十八、后续可扩展方向首版已经验证.7z基础能力。后续可以继续补进度回调取消任务list 列表能力多文件目录压缩 UI密码压缩实测大文件压缩稳定性测试1000 小文件压缩测试多 ABI 构建OHPM 发布流程从 console bridge 改成更底层 archive API其中最值得做的是进度回调和取消任务。当前复用Main2是最小可复现路径但它更像 console 程序封装。真正要做成生产级基础库后续可以绕过 console 层直接使用 7-Zip archive API这样更容易做并发、进度和取消。十九、结语这次sevenzip-ohos适配最有价值的地方不是写了一个按钮页面而是把 7-Zip Native 核心真正带进了鸿蒙 PC 应用运行时。过程中几个关键经验非常明确7-Zip 源文件清单必须从官方Alone7z基准生成不要编译MainAr.cppcommand bridge 可以复用Main2但要加互斥锁NAPI 必须把错误信息带回 ArkTSCMake 不能简单把 7-Zip 注册对象塞进 STATIC 静态库鸿蒙 PC 真机验证要先走应用沙箱路径签名、SDK 路径和 Hvigor daemon 缓存会影响最终运行最终结果已经证明ArkTS - HAR - NAPI - 7-Zip Native - 沙箱文件系统这条链路可以在鸿蒙 PC 上实际跑通。参考资料7-Zip LZMA SDK7-Zip GitHub 源码OpenHarmony Node-API 开发流程OpenHarmony NDK CMake 构建说明OpenHarmony ArkTS 静态加载 Native 模块