1. 项目背景与核心需求
在鸿蒙（HarmonyOS）应用开发过程中，我们经常会遇到需要复用现有C/C++代码库的情况。这些代码库通常以动态链接库（.so文件）的形式存在，如何在鸿蒙应用中正确加载和调用这些so文件，是很多开发者面临的现实问题。
我最近在开发一个图像处理应用时，就遇到了这个需求：需要将一个用C++编写的高性能图像算法库集成到鸿蒙应用中。经过多次实践和踩坑，总结出了一套完整的解决方案。与Android平台不同，鸿蒙的Native API设计和加载机制有其特殊性，这也是很多开发者容易出错的地方。
2. 环境准备与工具链配置
2.1 开发环境要求
要实现在鸿蒙中调用自定义so，你需要准备以下环境：
- DevEco Studio 3.0或更高版本
- HarmonyOS SDK API 8或以上
- NDK工具链（用于编译C/C++代码）
- CMake 3.10.2或更高版本
注意：鸿蒙的NDK与Android NDK不兼容，必须使用鸿蒙官方提供的NDK工具链。
2.2 项目结构规划
合理的项目结构能避免很多后期问题。建议采用如下目录结构：
code复制project/
├── entry/
│ ├── src/
│ │ ├── main/
│ │ │ ├── cpp/ # C/C++源代码
│ │ │ ├── resources/ # 资源文件
│ │ │ ├── config.json # 应用配置文件
│ │ │ └── java/ # Java/JS代码
│ │ └── ohosTest/ # 测试代码
├── build.gradle # 模块构建配置
└── settings.gradle # 项目设置
3. 创建Native模块
3.1 配置CMakeLists.txt
在cpp目录下创建CMakeLists.txt文件，这是编译so的关键配置文件：
cmake复制cmake_minimum_required(VERSION 3.10.2)
project(MyNativeLib)
# 设置编译选项
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -Wall")
# 添加源文件
add_library(mynative SHARED
native-lib.cpp
image-process.cpp)
# 查找系统库
find_library(log-lib libhilog_ndk.z.so)
# 链接库
target_link_libraries(mynative ${log-lib})
3.2 实现Native方法
在native-lib.cpp中实现具体的功能函数：
cpp复制#include <hilog/log.h>
#include <jni.h>
extern "C" {
JNIEXPORT jint JNICALL
Java_com_example_myapp_NativeLib_processImage(JNIEnv *env, jobject obj, jintArray pixels) {
jint *input = env->GetIntArrayElements(pixels, nullptr);
jsize length = env->GetArrayLength(pixels);
// 调用实际的图像处理算法
process_image_algorithm(input, length);
env->ReleaseIntArrayElements(pixels, input, 0);
return 0;
}
}
4. 构建配置与编译
4.1 配置build.gradle
在模块的build.gradle中添加NDK支持：
groovy复制android {
compileSdkVersion 8
buildToolsVersion "8.0.0"
defaultConfig {
externalNativeBuild {
cmake {
cppFlags "-std=c++11"
arguments "-DANDROID_STL=c++_shared"
}
}
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
externalNativeBuild {
cmake {
path "src/main/cpp/CMakeLists.txt"
version "3.10.2"
}
}
}
4.2 编译so文件
执行以下步骤生成so文件：
- 在DevEco Studio中点击Build > Make Module 'entry'
- 编译完成后，so文件会生成在build/intermediates/cmake目录下
- 将生成的so文件复制到src/main/resources/rawfile目录中
5. 在鸿蒙应用中加载so
5.1 创建Native接口类
java复制public class NativeLib {
static {
System.loadLibrary("mynative");
}
public native int processImage(int[] pixels);
}
5.2 配置应用权限
在config.json中添加必要的权限：
json复制{
"module": {
"reqPermissions": [
{
"name": "ohos.permission.READ_USER_STORAGE",
"reason": "Access native library"
}
]
}
}
6. 实际调用示例
6.1 在Ability中调用Native方法
java复制public class MainAbility extends Ability {
@Override
public void onStart(Intent intent) {
super.onStart(intent);
NativeLib nativeLib = new NativeLib();
int[] imageData = getImageData(); // 获取图像数据
nativeLib.processImage(imageData);
}
}
6.2 错误处理机制
建议添加完善的错误处理：
java复制try {
NativeLib nativeLib = new NativeLib();
int result = nativeLib.processImage(data);
if (result != 0) {
HiLog.error(LABEL, "Native processing failed with code: " + result);
}
} catch (UnsatisfiedLinkError e) {
HiLog.error(LABEL, "Failed to load native library: " + e.getMessage());
}
7. 性能优化与调试技巧
7.1 减少JNI调用开销
- 批量处理数据，避免频繁的JNI调用
- 使用DirectBuffer处理大数据量
- 缓存方法ID和类引用
7.2 内存管理注意事项
- 及时释放GetXXXArrayElements获取的数组指针
- 避免在Native层长期持有Java对象引用
- 使用GetPrimitiveArrayCritical处理性能关键代码
7.3 调试技巧
- 使用hilog输出Native层日志：
cpp复制OH_LOG_DEBUG(LOG_APP, "Debug message: %d", value); - 在DevEco Studio中配置Native调试
- 使用addr2line工具分析Native崩溃日志
8. 常见问题与解决方案
8.1 so文件加载失败
可能原因及解决方案：
-
so文件未正确打包到应用中
- 检查so文件是否在resources/rawfile目录
- 确认文件名和路径正确
-
ABI不匹配
- 检查设备的CPU架构
- 确保gradle中配置了正确的abiFilters
-
依赖库缺失
- 使用readelf -d查看so依赖
- 确保所有依赖库都打包到应用中
8.2 JNI方法找不到
排查步骤：
- 检查方法签名是否完全匹配
- 确认方法名和类名正确
- 使用javap -s查看准确的签名
8.3 性能问题优化
优化建议：
- 使用perf工具分析热点函数
- 考虑使用NEON指令集优化关键算法
- 减少JNI边界的数据拷贝
9. 高级应用场景
9.1 多线程调用Native方法
在Native层正确处理多线程：
cpp复制JavaVM* g_jvm = nullptr;
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
g_jvm = vm;
return JNI_VERSION_1_6;
}
void* thread_func(void* arg) {
JNIEnv* env;
g_jvm->AttachCurrentThread(&env, nullptr);
// 调用JNI方法
g_jvm->DetachCurrentThread();
return nullptr;
}
9.2 回调Java方法
从Native层回调Java方法：
cpp复制jclass clazz = env->GetObjectClass(obj);
jmethodID callback = env->GetMethodID(clazz, "onProgress", "(I)V");
env->CallVoidMethod(obj, callback, progress);
9.3 使用C++类与异常处理
在JNI中封装C++类：
cpp复制class ImageProcessor {
public:
void process(int* data, int length);
};
extern "C" JNIEXPORT jlong JNICALL
Java_com_example_ImageProcessor_create(JNIEnv* env, jobject obj) {
return reinterpret_cast<jlong>(new ImageProcessor());
}
extern "C" JNIEXPORT void JNICALL
Java_com_example_ImageProcessor_process(
JNIEnv* env, jobject obj, jlong handle, jintArray data) {
auto processor = reinterpret_cast<ImageProcessor*>(handle);
// 处理数据
}
10. 安全注意事项
-
输入验证
- 对所有从Java层传入的参数进行验证
- 检查数组长度和指针有效性
-
异常处理
- 使用ExceptionCheck检查Java异常
- 避免在Native层抛出未处理的异常
-
内存安全
- 使用RAII管理资源
- 避免内存泄漏和野指针
-
敏感数据保护
- 及时清除内存中的敏感数据
- 避免在日志中输出敏感信息
在实际项目中，我发现正确处理Native层的生命周期特别重要。鸿蒙应用可能会被快速销毁和重建，如果不妥善管理Native资源，很容易导致内存泄漏或崩溃。建议为每个Native类实现明确的销毁方法，并在Ability的onStop或onDestroy中调用它们。