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