一、前置思考

1.1 为什么需要 Native 适配？

纯 ArkTS 做不到的:
  → 音视频编解码 (FFmpeg/OpenH264)
  → 图像处理 (OpenCV)
  → 加密算法 (OpenSSL/国密)
  → 游戏引擎 / 高性能计算
  → 已有 C/C++ 资产 (公司存量代码)

解决方案: 通过 NAPI 把 C/C++ 能力桥接给 ArkTS
  → 性能敏感逻辑跑 Native，业务逻辑留在 ArkTS

1.2 一次 Native 适配的完整链路

选型 (NAPI/FFI/Worker) → 交叉编译 → NAPI 封装
  → 数据序列化/内存管理 → 桥接测试
  → 性能 Benchmark → 发布

二、核心原理

2.1 NAPI 桥接原理

ArkTS (JS 引擎) ←→ NAPI 层 ←→ C/C++ 库

  ArkTS 调用:
    const result = nativeAdd(1, 2);
  NAPI 层:
    接收 napi_value 参数 → 转 C 类型 → 调 C++ 函数
    → 结果转回 napi_value 返回

关键机制:
  → napi_env: 运行时上下文
  → napi_callback_info: 调用信息 (参数/this)
  → napi_create_function: 注册导出函数
  → 内存: JS 对象由 GC 管理，Native 侧需管理引用

2.2 NAPI 模块注册

// native/src/native_init.cpp
#include "napi/native_api.h"

static napi_value Add(napi_env env, napi_callback_info info) {
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    double a = 0, b = 0;
    napi_get_value_double(env, args[0], &a);
    napi_get_value_double(env, args[1], &b);

    napi_value result;
    napi_create_double(env, a + b, &result);
    return result;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        {"add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr}
    };
    napi_define_properties(env, exports, 1, desc);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterModule() {
    napi_module_register(&demoModule);
}

2.3 交叉编译配置

entry/src/main/cpp/CMakeLists.txt:
  cmake_minimum_required(VERSION 3.5.0)
  project(mylib)

  set(NATIVE_ROOT ${CMAKE_CURRENT_SOURCE_DIR})
  include_directories(${NATIVE_ROOT}/include)

  # 引入第三方库 (已交叉编译为 .a/.so)
  add_library(myffmpeg STATIC IMPORTED)
  set_target_properties(myffmpeg PROPERTIES
    IMPORTED_LOCATION ${NATIVE_ROOT}/libs/${OHOS_ARCH}/libmyffmpeg.a)

  add_library(entry SHARED native_init.cpp)
  target_link_libraries(entry PUBLIC myffmpeg)
  target_link_options(entry PUBLIC -lz -lm)

多架构:
  arm64-v8a / armeabi-v7a / x86_64
  → OHOS_ARCH 由构建系统注入，自动选择对应产物

2.4 Rust FFI 跨语言调用

Rust 编译为 C ABI 动态库 → 通过 NAPI 或 FFI 调用

Rust 侧:
  #[no_mangle]
  pub extern "C" fn rs_process(data: *const u8, len: usize) -> i32 {
      // 高性能处理逻辑
      0
  }

调用方式:
  → 方案A: Rust 编译 .so → NAPI 再包一层
  → 方案B: ArkTS 用 dlopen + ffi 直接调 C ABI
  → 方案C: Rust 直接实现 NAPI (napi-rs 生态)

选型: 生态成熟度 / 团队技能 / 性能要求

三、源码/API 深度解析

3.1 ArkTS 侧调用 Native

// 导入 Native 模块
import nativeModule from 'libentry.so';

// 调用 Native 函数
const sum: number = nativeModule.add(1, 2);

// 异步调用 (CPU 密集任务避免阻塞主线程)
// 方案: TaskPool 中执行 Native 调用
import { taskpool } from '@kit.ArkTS';

@Concurrent
function heavyNativeTask(data: ArrayBuffer): number {
  // 在子线程执行 Native 调用
  return nativeModule.process(data);
}

const task: taskpool.Task = new taskpool.Task(heavyNativeTask, buffer);
const result: number = await taskpool.execute(task) as number;

3.2 数据传递与内存管理

// 大数据传递: ArrayBuffer 零拷贝
static napi_value Process(napi_env env, napi_callback_info info) {
    size_t argc = 1;
    napi_value args[1];
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    void* data = nullptr;
    size_t len = 0;
    // 获取 ArrayBuffer 数据指针 (不拷贝)
    napi_get_arraybuffer_info(env, args[0], &data, &len);

    // 直接处理 data → 零拷贝高性能
    process_inplace(static_cast<uint8_t*>(data), len);

    napi_value result;
    napi_get_boolean(env, true, &result);
    return result;
}

// 引用管理:
//   napi_create_reference / napi_delete_reference
//   防止 JS 对象被 GC 回收后 Native 仍持有
//   Native 创建的对象需 napi_*_release 释放

3.3 性能对比 Benchmark

场景: 大数组求和 1000 万次

ArkTS 纯 JS 循环:  ~ 180ms
NAPI + C 循环:      ~ 12ms   (15x)
NAPI + SIMD:        ~ 4ms    (45x)
Rust FFI:           ~ 6ms    (30x)

结论:
  → 计算密集: 必须 Native (数字信号/图像/编解码)
  → IO 密集: Native 收益有限，优先优化调度
  → 调用频繁的小函数: 注意桥接开销 (每次调用有成本)

四、企业级实战落地

4.1 适配方案选型

场景	方案	理由
已有 C/C++ 库	NAPI 封装	生态成熟、官方支持
Rust 高性能库	Rust 编译 so + NAPI	内存安全 + 高性能
简单小函数	ArkTS 直接实现	避免桥接开销
超大计算	Native + TaskPool	子线程执行不卡 UI
音视频编解码	FFmpeg + NAPI	行业标准方案

4.2 完整示例：跨语言调用演示

@Entry
@ComponentV2
struct CrossLangAdaptDemo {
  @Local result: string = '';
  @Local logs: string[] = [];

  private runBridgeDemo(): void {
    this.logs = [];
    this.result = '';
    this.log('🔌 跨语言调用演示开始');
    this.log('① ArkTS 调用 NAPI: nativeAdd(10, 32)');
    this.log('   → NAPI 层转 C double → C++ 函数计算');
    this.log('   → 结果 42 转回 napi_value');
    this.log('② 大数据传递: ArrayBuffer 零拷贝');
    this.log('   100MB 缓冲区 → 指针直达, 无拷贝');
    this.log('③ 子线程执行: TaskPool + @Concurrent');
    this.log('   避免阻塞 UI 主线程');
    this.log('④ 性能对比: 千万次计算');
    this.log('   ArkTS: 180ms | NAPI+C: 12ms (15x)');
    this.log('   SIMD: 4ms (45x) | Rust: 6ms (30x)');
    this.result = '桥接链路验证通过 ✅';
  }

  build() {
    Column({ space: 12 }) {
      Text('🔀 跨语言适配演示').fontSize(20).fontWeight(FontWeight.Bold)
      Text(this.result !== '' ? this.result : 'NAPI / FFI 桥接').fontSize(13).fontColor('#1B7C83')

      Row({ space: 8 }) {
        Button('▶ 模拟桥接调用').layoutWeight(1).height(40).fontSize(12)
          .onClick(() => this.runBridgeDemo())
        Button('清空').height(40).fontSize(12)
          .onClick(() => this.logs = [])
      }
      .width('100%')

      Scroll() {
        Column() {
          ForEach(this.logs, (l: string) => {
            Text(l).fontSize(11).lineHeight(18).fontColor('#24292F').width('100%')
          }, (l: string, i: number) => l + i)
        }.width('100%')
      }
      .layoutWeight(1).width('100%').scrollBar(BarState.Off)
    }
    .width('100%').height('100%').padding(16)
    .backgroundColor('#F6F8FA')
  }
}

4.3 Native 适配清单

1. 先 Benchmark 再动手: 确认 ArkTS 确实不够
2. 最小桥接面: NAPI 只暴露少量函数，逻辑留在 Native
3. 大数据走 ArrayBuffer 零拷贝
4. 耗时 Native 调用进 TaskPool，别卡主线程
5. 内存严格管理: 每个 napi_create 都要对应 release
6. 多架构产物: arm64/armv7/x86_64 全平台验证

五、问题排查与性能优化

问题	原因	解决
so 加载失败	架构不匹配/依赖缺失	校验 OHOS_ARCH 产物
崩溃无栈	Native 崩溃	符号化 + gdb 调试
内存泄漏	引用未释放	napi 引用管理审查
主线程卡顿	Native 计算阻塞	移入 TaskPool
数据拷贝多	类型转换频繁	用 ArrayBuffer 零拷贝
桥接开销大	小函数频繁调用	批量接口 / 纯 ArkTS

5.1 性能优化进阶

1. 批量处理: 1000 个小调用 → 1 个大调用 (降桥接开销)
2. SIMD 加速: 向量化计算 (NEON/AVX)
3. 内存复用: 预分配缓冲区，避免反复 malloc
4. 异步化: 回调/Promise 通知完成，不阻塞调用方
5. 缓存: 高频结果 Native 侧缓存，减少往返

六、高阶总结与最佳实践

1. 性能敏感才 Native：先 Benchmark 证明瓶颈，避免盲目桥接。
2. 最小桥接面：NAPI 是薄层，逻辑留在 Native，接口越少越好维护。
3. 零拷贝优先：ArrayBuffer 直传指针，是跨语言性能的关键。
4. 内存是 Native 的生命线：引用计数 + 对称释放，泄漏从源头杜绝。
5. 线程模型要清晰：Native 计算 + TaskPool 子线程，主线程永远流畅。

一句话记住：跨平台适配 = NAPI 薄桥接 + C/C++/Rust 高性能内核 + ArrayBuffer 零拷贝 + TaskPool 异步化，把"语言边界"变成"性能加速器"。