上一篇咱們把 Node-API 的基本流程走通了。但工程化用起來(lái)還會(huì)撞上一堆為什么這樣不行的問(wèn)題so 名字改了加載不到、Native 函數(shù)里開(kāi)個(gè)線程回調(diào) ArkTS 就 crash、模擬器跑得好好的真機(jī)崩了。這篇把 SO 命名、注冊(cè)、多線程、調(diào)試、性能這幾塊的約束和背后原因講清楚省得踩坑靠玄學(xué)。SO 命名規(guī)則ArkTS 側(cè)import xxx from libentry.so這一行背后對(duì)應(yīng)三個(gè)地方的名字必須對(duì)齊位置寫(xiě)法取值CMakeLists.txtadd_library(entry SHARED ...)entrynapi_init.cppdemoModule.nm_modname entryentryArkTS 側(cè)import xxx from libentry.solibentry.so規(guī)則是模塊名為entryso 文件名就是libentry.sonm_modname字段填entry不帶 lib 前綴和 .so 后綴ArkTS import 時(shí)寫(xiě)完整的libentry.so。大小寫(xiě)也要一致Entry和entry是兩個(gè)不同的模塊。這個(gè)對(duì)應(yīng)關(guān)系不是湊巧是加載鏈路硬性要求的ArkTS 引擎拿到import libentry.so去文件系統(tǒng)找libentry.sodlopen 加載so 加載時(shí)跑RegisterDemoModule把nm_modname entry注冊(cè)到模塊表ArkTS 引擎再根據(jù) import 路徑反查模塊表找到對(duì)應(yīng) exports 對(duì)象。任何一環(huán)名字不對(duì)要么 so 找不到要么模塊注冊(cè)了但查不到結(jié)果都是undefined。多模塊工程里每個(gè) Native 模塊都要有自己的 so 名不能圖省事都用entry。比如有l(wèi)ibcrypto.so和libimage.so兩個(gè)模塊nm_modname分別是crypto和image注冊(cè)入口函數(shù)名也要不一樣RegisterCryptoModule、RegisterImageModule否則符號(hào)沖突。注冊(cè)建議Init 函數(shù)加 staticstaticnapi_valueInit(napi_env env,napi_value exports){...}這個(gè)static不是可有可無(wú)的。C 里函數(shù)默認(rèn)有外部鏈接沒(méi)static的話符號(hào)會(huì)導(dǎo)出到 so 的符號(hào)表兩個(gè) so 都有Init函數(shù)時(shí)鏈接器可能把調(diào)用解析到錯(cuò)誤的那個(gè)上。加了static把符號(hào)限制在文件內(nèi)就不會(huì)串。注冊(cè)入口函數(shù)名唯一externC__attribute__((constructor))voidRegisterDemoModule(){...}extern C去掉 C name mangling__attribute__((constructor))讓 so 加載時(shí)自動(dòng)調(diào)用。這個(gè)函數(shù)名必須全工程唯一。兩個(gè) so 都導(dǎo)出RegisterDemoModule符號(hào)dlopen 第二個(gè) so 時(shí)可能覆蓋第一個(gè)的符號(hào)導(dǎo)致第一個(gè)模塊沒(méi)被注冊(cè)。實(shí)際工程里建議按模塊名命名RegisterCryptoModule、RegisterImageModule一眼看出歸屬也不容易重名。重復(fù)注冊(cè)不會(huì)生效同一個(gè) so 被多次 importnapi_module_register會(huì)被調(diào)用多次但模塊表里只保留第一次注冊(cè)的結(jié)果。所以不用擔(dān)心 ArkTS 側(cè)多個(gè)文件 import 同一個(gè) so 導(dǎo)致重復(fù)注冊(cè)。多線程限制這是 Node-API 工程化里最容易出問(wèn)題的地方。規(guī)則只有一條但后果很?chē)?yán)重每個(gè)引擎實(shí)例對(duì)應(yīng)一個(gè) ArkTS 線程實(shí)例上的對(duì)象不能跨線程操作否則 crash。拆開(kāi)看Node-API 接口只能在 ArkTS 線程用所有napi_*函數(shù)都假設(shè)調(diào)用方在創(chuàng)建env的那個(gè)線程。在 Native 自己開(kāi)的 std::thread 里調(diào)napi_create_double(env, ...)env 是從 ArkTS 線程拿的跨線程用行為未定義大概率 crash。env 和線程綁定napi_env不是個(gè)無(wú)狀態(tài)句柄它背后是當(dāng)前線程的引擎上下文。同一個(gè) env 不能在兩個(gè)線程用。napi_value 不能跨線程持有一個(gè)線程創(chuàng)建的napi_value在另一個(gè)線程里是無(wú)效的GC 可能已經(jīng)把它回收了。Native子線程ArkTS線程異步派發(fā)ArkTS 調(diào) Native 函數(shù)CallNative 執(zhí)行env 在此線程有效返回 napi_valuestd::thread 啟動(dòng)在此線程調(diào) napi_*? env 跨線程想跨線程怎么辦Native 側(cè)有耗時(shí)計(jì)算想開(kāi)線程做做完了想通知 ArkTS不能直接拿 env 調(diào)napi_call_function。正確做法是Native 子線程里把數(shù)據(jù)算完結(jié)果存成 C 原生類型int、std::string這種不是napi_value。通過(guò)線程安全的隊(duì)列把結(jié)果傳回 ArkTS 線程。ArkTS 線程從隊(duì)列取結(jié)果在 ArkTS 線程里調(diào)napi_create_*包成napi_value返回?；蛘哂胣api_threadsafe_functionTSFN這個(gè)專門(mén)為跨線程回調(diào)設(shè)計(jì)的接口。它創(chuàng)建一個(gè)線程安全的函數(shù)句柄任意線程都能往里塞調(diào)用請(qǐng)求引擎在 ArkTS 線程上串行執(zhí)行。TSFN 的 API 比較繁瑣但跨線程回調(diào) ArkTS 這是唯一靠譜的路。一個(gè)錯(cuò)誤示例// 錯(cuò)誤在 Native 子線程里用 env 調(diào) ArkTS callbackstaticnapi_valueBadAsyncCall(napi_env env,napi_callback_info info){size_t argc1;napi_value args[1]{nullptr};napi_get_cb_info(env,info,argc,args,nullptr,nullptr);std::thread([env,args](){// ? env 和 args[0] 都屬于 ArkTS 線程這里用會(huì) crashnapi_value argv;napi_create_int32(env,42,argv);napi_value result;napi_call_function(env,nullptr,args[0],1,argv,result);}).detach();returnnullptr;}這段代碼在子線程里用 env 創(chuàng)建 napi_value 并調(diào)用 callback運(yùn)行時(shí)大概率 crash且堆棧看不出明顯原因因?yàn)?crash 發(fā)生在 GC 或引擎內(nèi)部狀態(tài)被破壞之后。這種 bug 極難定位必須從源頭避免。代碼調(diào)試設(shè)備選擇設(shè)備適合場(chǎng)景注意真機(jī)性能調(diào)優(yōu)、Native crash 復(fù)現(xiàn)優(yōu)先選模擬器無(wú)真機(jī)或無(wú)權(quán)限時(shí)部分 Native 行為和真機(jī)有差異預(yù)覽器? 不能調(diào) Native只渲染組件不加載 so預(yù)覽器調(diào) Native 會(huì)報(bào)TypeError: undefined is not callable因?yàn)轭A(yù)覽器根本沒(méi) dlopen so。這個(gè)報(bào)錯(cuò)看起來(lái)像 ArkTS 寫(xiě)錯(cuò)了其實(shí)是預(yù)覽器不支持換模擬器或真機(jī)就好。真機(jī)和模擬器差異主要在 CPU 架構(gòu)真機(jī) arm64模擬器 x86_64和系統(tǒng)庫(kù)版本。涉及 ABI 細(xì)節(jié)如結(jié)構(gòu)體對(duì)齊、調(diào)用約定的 Native 代碼模擬器過(guò)了真機(jī)不一定過(guò)最終驗(yàn)證得在真機(jī)。日志調(diào)試Native 側(cè)打日志用__hiwrite_logHiLog#includehilog/log.h#defineLOG_TAGMyNative#defineLOG_DOMAIN0x3200staticnapi_valueCallNative(napi_env env,napi_callback_info info){// ... 業(yè)務(wù)邏輯OH_LOG_Print(LOG_APP,LOG_INFO,LOG_DOMAIN,LOG_TAG,CallNative result: %{public}f,sum);returnresult;}ArkTS 側(cè)的console.log和 Native 側(cè)的 HiLog 都能在 hilog 流里看到。Native crash 的堆棧在 crash 發(fā)生后用hdc shell hilog | grep -A 30 SIGSEGV抓。斷點(diǎn)調(diào)試DevEco Studio 支持雙端斷點(diǎn)ArkTS 和 C 都能下斷點(diǎn)調(diào)試時(shí)在同一個(gè) session 里來(lái)回切。配置好 Native C 工程后Debug 模式運(yùn)行ArkTS 調(diào)進(jìn) Native 時(shí)會(huì)自動(dòng)切到 C 調(diào)試視圖變量、調(diào)用棧都能看。混合調(diào)試的前提是 so 帶 debug 符號(hào)CMake 里set(CMAKE_BUILD_TYPE Debug)或 RelWithDebInforelease 模式 strip 過(guò)符號(hào)的 so 斷點(diǎn)下不準(zhǔn)。性能注意事項(xiàng)跨邊界開(kāi)銷每次 ArkTS 調(diào) Native 都有固定開(kāi)銷參數(shù)從napi_value轉(zhuǎn)成 C 類型napi_get_value_*調(diào)用進(jìn)入 Native 上下文返回值從 C 類型包回napi_valuenapi_create_*引擎狀態(tài)切換單次調(diào)用開(kāi)銷在微秒級(jí)看著不大但在循環(huán)里調(diào)幾十萬(wàn)次就明顯了。// 慢循環(huán)里反復(fù)跨邊界letsum0;for(leti0;i1000000;i){sumnativeModule.add(sum,i);}// 快一次跨邊界C 里循環(huán)letsumnativeModule.rangeSum(0,1000000);對(duì)應(yīng)的 Cstaticnapi_valueRangeSum(napi_env env,napi_callback_info info){size_t argc2;napi_value args[2]{nullptr};napi_get_cb_info(env,info,argc,args,nullptr,nullptr);int64_tstart,end;napi_get_value_int64(env,args[0],start);napi_get_value_int64(env,args[1],end);int64_tsum0;for(int64_tistart;iend;i){sumi;// 純 C 循環(huán)不跨邊界}napi_value ret;napi_create_int64(env,sum,ret);returnret;}實(shí)測(cè)百萬(wàn)次加法循環(huán)跨邊界版本要幾十毫秒一次跨邊界版本不到 1 毫秒。差距全在邊界開(kāi)銷上。數(shù)據(jù)轉(zhuǎn)換成本不同類型轉(zhuǎn)換成本差很多類型轉(zhuǎn)換方式成本number (int/double)napi_get_value_double低booleannapi_get_value_bool低string兩次調(diào)用拿長(zhǎng)度拷貝中Object逐字段 napi_get_named_property高ArrayBuffernapi_get_arraybuffer_info 拿指針極低傳大塊數(shù)值數(shù)據(jù)用ArrayBufferNative 側(cè)直接拿到內(nèi)存指針操作沒(méi)有拷貝staticnapi_valueProcessArray(napi_env env,napi_callback_info info){size_t argc1;napi_value args[1]{nullptr};napi_get_cb_info(env,info,argc,args,nullptr,nullptr);void*datanullptr;size_t length0;napi_get_arraybuffer_info(env,args[0],data,length);// 直接操作內(nèi)存零拷貝double*arrstatic_castdouble*(data);size_t nlength/sizeof(double);for(size_t i0;in;i){arr[i]arr[i]*2.0;// 原地翻倍}returnnullptr;}ArkTS 側(cè)constbufnewArrayBuffer(8*1000);// 1000 個(gè) doubleconstviewnewFloat64Array(buf);for(leti0;i1000;i)view[i]i;nativeModule.processArray(buf);// 原地修改圖像處理、矩陣運(yùn)算這種場(chǎng)景ArrayBuffer 是標(biāo)配。舉個(gè)栗子Native 側(cè)計(jì)時(shí)器回調(diào) ArkTS需求ArkTS 調(diào) Native 啟動(dòng)一個(gè)定時(shí)器N 秒后 Native 回調(diào) ArkTS 通知。子線程里不能直接用 env得用 TSFN。#includethread#includechronostaticnapi_valueStartTimer(napi_env env,napi_callback_info info){size_t argc2;napi_value args[2]{nullptr};napi_get_cb_info(env,info,argc,args,nullptr,nullptr);doubledelayMs;napi_get_value_double(env,args[0],delayMs);// 創(chuàng)建 TSFN把 ArkTS callback 包裝成線程安全句柄napi_threadsafe_function tsfn;napi_value workName;napi_create_string_utf8(env,TimerCallback,NAPI_AUTO_LENGTH,workName);napi_create_threadsafe_function(env,args[1],nullptr,workName,0,1,nullptr,nullptr,nullptr,[](napi_env env,napi_value/*cb*/,void*/*context*/,void*data){// 在 ArkTS 線程執(zhí)行napi_value cbstatic_castnapi_value(data);napi_value undefined;napi_get_undefined(env,undefined);napi_value result;napi_call_function(env,undefined,cb,0,nullptr,result);},tsfn);// 子線程里等待然后通過(guò) TSFN 觸發(fā)回調(diào)std::thread([tsfn,delayMs](){std::this_thread::sleep_for(std::chrono::milliseconds(static_castint(delayMs)));// Acquire 一次把 callback 推進(jìn)隊(duì)列napi_acquire_threadsafe_function(tsfn);napi_call_threadsafe_function(tsfn,nullptr,napi_tsfn_nonblocking);napi_release_threadsafe_function(tsfn,napi_tsfn_release);}).detach();returnnullptr;}ArkTS 側(cè)importnativeModulefromlibentry.so;nativeModule.startTimer(2000,(){console.log(2 秒到了);});TSFN 的 API 看著繁瑣但套路固定創(chuàng)建時(shí)傳一個(gè)在 ArkTS 線程執(zhí)行的回調(diào)子線程里napi_call_threadsafe_function把數(shù)據(jù)塞進(jìn)去引擎在 ArkTS 線程上串行調(diào)用那個(gè)回調(diào)。所有跨線程回調(diào) ArkTS 的場(chǎng)景都是這個(gè)模式。注意一下下so 改了不生效CMake 緩存問(wèn)題。DevEco 里 Build Clean Project再重新 build。或者直接刪entry/build/default目錄。crash 在 OS_GC_Thread 線程堆棧里看到OS_GC_Thread、CompressGCMarker這類字樣多半是 Native 側(cè)把 napi_value 跨線程持有GC 移動(dòng)對(duì)象時(shí)指針失效?；夭?Native 代碼里有沒(méi)有把 napi_value 存到 C 全局變量或子線程閉包里。模擬器跑通真機(jī)崩檢查 ABI 相關(guān)代碼。結(jié)構(gòu)體對(duì)齊、long大小arm64 是 8 字節(jié)x86_64 也是 8但 x86 是 4、未定義行為UB在不同架構(gòu)表現(xiàn)不同。Sanitize 工具能幫著抓 UB。import 報(bào) undefinedso 沒(méi)編出來(lái)或名字不對(duì)。先看entry/build下有沒(méi)有 libentry.so再看 CMake 里add_library名字和nm_modname對(duì)不對(duì)。Native 側(cè)內(nèi)存泄漏用napi_create_*創(chuàng)建的 napi_value 由 GC 管不用手動(dòng)釋放。但 Native 側(cè)自己malloc/new的內(nèi)存要自己釋放引擎不會(huì)代勞。napi_create_external創(chuàng)建的 external 對(duì)象可以掛 finalize 回調(diào)對(duì)象被 GC 時(shí)回調(diào)里釋放 Native 內(nèi)存?？偨Y(jié)一下下跨邊界調(diào)用次數(shù)是性能關(guān)鍵指標(biāo)不是單次調(diào)用快慢。把 N 次小調(diào)用合并成 1 次大調(diào)用性能能差幾個(gè)數(shù)量級(jí)。TSFN 是跨線程回調(diào)的唯一正規(guī)路徑。別想著用全局變量存 env 然后子線程里調(diào)遲早 crash。Native 側(cè)的 C 異常不會(huì)自動(dòng)傳到 ArkTStry/catch 在 ArkTS 側(cè)抓不到。Native 側(cè)要么自己 catch 完返回錯(cuò)誤碼要么用napi_throw_error拋 ArkTS 異常。線上 crash 排查靠 hilog 抓堆棧但 release 包符號(hào)被 strip 了堆棧是地址。要保留一份帶符號(hào)的 so 做離線符號(hào)化DevEco build 出來(lái)的entry/build/default/obj/default/entry/下有未 strip 的 so。