摘要

在实际的鸿蒙应用开发中，很少有项目是完全“从零开始”的。无论是统计埋点、支付登录、音视频处理，还是 AI 能力接入，都会或多或少依赖第三方 SDK。但很多同学在第一次接触鸿蒙时，会发现一个问题：Android 那一套 SDK 集成经验，到了鸿蒙这里并不能直接照搬。

本文结合当前鸿蒙应用的真实开发现状，从工程结构、能力形态和实际业务场景出发，系统讲清楚鸿蒙中集成第三方 SDK 的常见方式，并配合可运行的 ArkTS Demo 代码，帮助你在做课程设计、实训项目或真实商业项目时少踩坑。

引言

随着 HarmonyOS 生态逐渐完善，越来越多的第三方厂商开始提供适配鸿蒙的 SDK，但形态并不统一。有的直接提供 ArkTS 包，有的仍然是 C/C++ 库，还有相当一部分能力其实已经云化，只需要调用接口即可。

这也导致一个现象：

• 新手不知道“该用哪种方式集成”
• 集成成功了，但不知道初始化、权限、生命周期怎么配合
• 项目能跑，但一到答辩或面试就说不清楚原理

下面的内容，我会按真实项目的思路来拆解，而不是只停留在“怎么引包”。

鸿蒙中第三方 SDK 的整体思路

在鸿蒙里，集成第三方 SDK 本质上就是一件事：

让第三方能力，能够在你的 Ability 生命周期中被正确初始化、调用和释放。

根据 SDK 的实现方式，常见可以分为三类：

ArkTS 形式的 SDK

这是目前最推荐、也最常见的一种方式，体验上最接近前端 npm 包。

Native C/C++ SDK

多用于音视频、算法、底层能力，需要通过 NAPI 暴露给 ArkTS。

服务型 SDK

不需要本地集成，直接通过 HTTP 或云接口调用。

下面我们逐个展开。

ArkTS 形式第三方 SDK 的集成方式

适用场景说明

ArkTS SDK 通常用于：

• 统计与埋点
• 日志上报
• 业务型工具库
• 轻量 AI 能力封装

如果一个 SDK 官方明确支持 HarmonyOS，并提供 .har 包或包名依赖，优先选择这种方式。

引入 SDK 依赖

在模块的 oh-package.json5 中声明依赖：

{
  "dependencies": {
    "@thirdparty/analytics": "1.0.0"
  }
}

如果是本地 SDK，可以这样写：

{
  "dependencies": {
    "@thirdparty/analytics": "./libs/analytics.har"
  }
}

这一步的本质，是把第三方 SDK 作为一个 ArkTS 模块加入工程依赖树。

在 Ability 中初始化 SDK（可运行 Demo）

import analytics from '@thirdparty/analytics'

@Entry
@Component
struct Index {
  aboutToAppear() {
    analytics.init({
      appKey: 'demo_app_key',
      debug: true
    })
  }

  build() {
    Column() {
      Button('点击上报事件')
        .onClick(() => {
          analytics.track('click_button')
        })
    }
  }
}

代码说明

• aboutToAppear 中初始化 SDK，符合页面生命周期
• init 通常只做一次，全局能力不建议反复初始化
• track 代表一次真实业务事件上报

在真实项目中，这类 SDK 往往会被进一步封装到单例工具类中，而不是直接写在页面里。

Native C/C++ SDK 的集成方式

为什么需要 Native SDK

在以下场景中，ArkTS 往往不够用：

• 音视频编解码
• 图像算法、人脸识别
• 硬件驱动相关能力

这类 SDK 多数以 C/C++ 形式提供，需要通过 NAPI 才能给 ArkTS 调用。

Native 层封装示例

CMake 中引入 SDK：

add_library(third_sdk SHARED third_sdk.cpp)

NAPI 暴露接口：

#include <napi/native_api.h>

napi_value StartSdk(napi_env env, napi_callback_info info) {
    return nullptr;
}

napi_value Init(napi_env env, napi_value exports) {
    napi_value fn;
    napi_create_function(env, nullptr, 0, StartSdk, nullptr, &fn);
    napi_set_named_property(env, exports, "start", fn);
    return exports;
}

ArkTS 调用 Native 能力

import nativeSdk from 'libthird_sdk.so'

nativeSdk.start()

代码说明

• ArkTS 并不关心底层实现
• Native SDK 负责性能和底层能力
• ArkTS 只作为调用入口和业务调度层

在真实项目中，这一层往往会增加异常处理和线程管理。

服务型 SDK 的接入方式

为什么越来越多 SDK 走服务化

很多能力已经不再推荐本地集成，例如：

• AI 识别
• 配置下发
• 数据分析

原因很简单：

• 不依赖平台
• 更新成本低
• 安全性更可控

HTTP 调用示例（可运行）

import http from '@ohos.net.http'

let client = http.createHttp()

client.request(
  'https://api.third.com/data',
  {
    method: http.RequestMethod.GET,
    header: {
      'Authorization': 'Bearer demo_token'
    }
  },
  (err, data) => {
    if (!err) {
      console.log(data.result)
    }
  }
)

代码说明

• http 模块是鸿蒙系统能力
• 第三方服务只需要遵守接口规范
• Token 一般由登录或后台下发

结合实际的应用场景分析

场景一：应用行为统计

典型做法：

• ArkTS 统计 SDK
• 页面进入和按钮点击时上报

analytics.track('page_enter_home')

适合课程设计、毕业设计中的“数据分析模块”。

场景二：音视频能力接入

• 使用 Native SDK
• ArkTS 只做控制和 UI

nativeSdk.start()

适合智慧屏、直播类应用。

场景三：AI 云能力调用

• 不引 SDK
• 直接调用服务

client.request('https://api.ai.com/recognize', ...)

适合轻量 AI 场景，避免包体过大。

QA 常见问题

Q1：SDK 初始化应该放哪里？

优先放在 Ability 或应用入口，不要写在 build 中。

Q2：所有 SDK 都要申请权限吗？

不一定，但只要涉及网络、设备信息，就需要在 module.json5 中声明。

Q3：ArkTS 和 Native 能混用吗？

可以，而且在复杂项目中非常常见。

总结

在鸿蒙中集成第三方 SDK，没有想象中复杂，关键是选对方式：

• 能用 ArkTS 的，就不要上 Native
• 能用服务的，就不要集成本地 SDK
• 初始化要结合生命周期