NAPI 双层架构：ArkTS 加 Native

Air 系列全部 90 个工程共享同一个总架构：ArkTS 薄壳加 native 核心，两层之间靠 NAPI 桥接。这篇把这个双层架构的总则讲清楚，它是后面一切工程实践的地基。

▍为什么是双层
ArkTS 层擅长系统交互：窗口、权限、输入法、文件选择器、分享，这些能力只有 ArkTS 侧是完整的一等公民。native 层擅长计算与渲染：上游代码、图形管线、多线程都在这边。双层架构就是让每层干自己最擅长的事，中间用明确接口通信。

▍NAPI 桥的设计原则
原则一，壳要薄：ArkTS 侧只做窗口宿主、菜单渲染、系统桥接，不写业务逻辑。原则二，桥面要窄：NAPI 接口数量控制在一个屏幕能看全的量级，参数用简单的可序列化类型，复杂结构走 JSON。原则三，线程纪律：ArkTS 主线程绝不阻塞——native 重活全在后台线程，跨线程回调一律走线程安全函数（TSFN）机制投递回 JS 线程，直接在后台线程调 NAPI 是崩溃高发区。原则四，桥不链库：hvigor 只编薄桥，绝不链接预编译库，上百个 so 全部运行时按拓扑序 dlopen。

▍单向依赖
依赖方向必须严格单向：ArkTS 调 native 方法、native 通过回调接口通知 ArkTS。native 侧永远不主动 import ArkTS 模块，ArkTS 侧永远不碰 native 内部数据结构。这条纪律守住，两层可以独立演进。

▍典型故障模式
违反纪律的报应都很典型：主线程被慢初始化卡住会触发系统看门狗冻屏；回调线程不对会随机崩在 NAPI 内部；桥里链了预编译库，打包工具闭包扫描会静默丢库，装机 dlopen 找不到模块。

▍一句话总结
ArkTS 是壳与系统界面，native 是引擎与逻辑，NAPI 是唯一的门，门要窄、要单向、要线程安全。所有 Air 工程的稳定运行都建立在这个朴素结构上。

更多真实移植案例，欢迎到 apps 板块翻看 56 篇《鸿蒙PC适配全记录》系列实录。