系统化掌握Android NDK开发 (JNI)

什么是Android NDK？

Android NDK的全称是Android Native Development Kit，即Android原生开发工具包，它是Google官方提供的一套开发工具集，核心作用是允许开发者在Android应用开发中，使用C、C++等"原生语言"编写应用的部分核心模块，最终将这些原生代码编译成适用于不同Android设备CPU架构（如arm64-v8a、armeabi-v7a、x86等）的动态链接库（.so 文件），并与Java/Kotlin编写的上层代码通过JNI（Java Native Interface）实现交互，共同构成完整的Android应用。

NDK开发与传统的Android SDK开发（Java/Kotlin）的主要区别和联系

区别:

联系：

NDK开发与SDK开发并非对立关系，而是互补协作的关系，共同构成完整的Android应用。两者通过JNI（Java Native Interface）实现通信，Java/Kotlin代码可通过native方法调用C/C++原生代码，原生代码也可通过JNI接口调用Android系统的Java API（如日志输出、UI更新）。

NDK的主要组成部分

Android NDK是一套完整的原生开发工具集合，核心组成部分围绕"代码编译-链接-调试-部署"的全流程设计，各组件相互配合，确保原生代码能顺利集成到Android应用中，主要组成部分如下。

原生工具链（Native Toolchain）

这是NDK的核心组件，包含编译器、链接器、汇编器等工具，负责将C/C++代码编译为适用于不同Android设备CPU架构的机器指令，NDK为每种支持的CPU架构（arm64-v8a、armeabi-v7a、x86、x86_64等）提供了对应的工具链，确保编译产物能适配不同设备。

编译器：

主要是Clang（NDK r11及以上默认编译器，支持C11、C++17等最新标准），早期版本也支持GCC（目前已逐步淘汰），用于将C/C++源代码编译为目标文件（.o文件）。

链接器：ld

ld（链接器），负责将多个目标文件与库文件（静态库.a、动态库.so）链接为最终的动态链接库（.so文件）。

汇编器：as（汇编器）

as（汇编器），负责将汇编代码编译为机器指令。

头文件（Header Files）

提供了C/C++代码与Android系统、Java层交互的接口声明，包括： JNI头文件 Android系统头文件 标准库头文件

JNI头文件：

如jni.h，定义了JNI的核心数据类型（jint、jstring、jobject等）、函数接口（如FindClass、GetMethodID等），是Java与C/C++交互的基础。

Android系统头文件：

如android/log.h（日志输出接口 __android_log_print）、android/native_window.h（原生窗口渲染接口）等，允许原生代码调用Android系统的核心功能。

标准库头文件：

如stdio.h、stdlib.h等C/C++标准库头文件，确保原生代码能使用标准库的基础功能（如文件操作、内存分配、字符串处理）。

系统库与第三方库（Libraries）

NDK内置了一系列预编译的静态库（.a）和动态库（.so），供开发者直接链接使用，避免重复开发。 包括 :C/C++标准库； Android系统原生库 ； 第三方开源库；

C/C++标准库：

如libc（C 标准库）、libstdc++（C++标准库）、libc++（NDK推荐的C++标准库，支持C++11及以上标准）。

Android系统原生库：

如liblog（日志输出库）、libz（压缩库）、libandroid（Android系统核心功能库）、libEGL/libGLESv2（图形渲染库，用于OpenGL ES开发）。

第三方开源库：

部分NDK版本内置了常用开源库（如libpn 图像库、libjpeg图像库），开发者可直接链接使用。

构建工具（Build Tools）

负责管理编译流程、配置编译参数（如目标架构、API级别、优化级别），核心工具包括如下。 包括阿: ndk-build ； CMake； Gradle插件；

ndk-build：

早期NDK开发的核心构建工具，基于Makefile语法，通过Android.mk（模块配置）和Application.mk（全局配置）文件定义编译规则，适用于简单项目。

CMake：

目前Google推荐的NDK构建工具，跨平台特性好，支持复杂项目的构建管理，通过CMakeLists.txt文件配置编译规则，与Android Studio集成度更高。

Gradle插件：

Android Studio中通过Android Gradle Plugin集成NDK构建能力，开发者可在build.gradle文件中配置NDK相关参数（如目标架构、CMake路径），实现构建流程自动化。

进行NDK开发需要准备哪些开发工具和环境？

核心开发IDE：Android Studio

推荐版本：Android Studio Hedgehog（2023.1.1）或更高稳定版本，可适配最新NDK版本（如r26），支持C++17及以上标准，同时修复了旧版本的构建缓存、调试链路等问题。

核心工具包：NDK（Native Development Kit）

匹配项目minSdkVersion：NDK每个版本对应最低支持的Android API级别（如NDK r26最低支持API 21，r25最低支持API 19），需确保NDK最低支持API≤项目minSdkVersion，否则编译后的.so文件无法在低版本设备运行。
适配功能需求：若需使用最新C++标准（如C++20）、新系统API（如Android 14原生特性），需选择较新版本NDK（r25及以上），若项目需兼容旧设备（minSdkVersion ≤ 16），需选择NDK r23及以下版本（r24起不再支持API 16及以下）。
规避不稳定版本：优先选择官方标记为"LTS（长期支持）"的版本（如r26 LTS），这类版本修复了关键bug，稳定性更高，适合商业项目，避免使用刚发布的预览版，可能存在构建或调试问题。

推荐版本：NDK r26 LTS（兼容API 21+，支持C++20，修复了大量编译与调试bug，是当前主流稳定版本）。

构建工具：CMake/ndk-build

用于定义原生代码的编译规则，将C/C++代码编译为.so文件，两者为互补关系，选择需结合项目复杂度。

CMake：

定位：Google当前推荐的构建工具，跨平台特性好（支持Windows/macOS/Linux），支持复杂项目构建（如多模块、第三方库集成），与Android Studio集成度最高。

版本要求：需与NDK版本兼容，Android Studio通常会捆绑适配的CMake版本（如NDK r26适配CMake 3.22+），建议使用IDE捆绑版本，避免版本不兼容导致的构建失败。

ndk-build：

定位：基于Makefile的传统构建工具，配置简单（依赖Android.mk/Application.mk），适合简单原生项目或legacy项目（旧项目迁移）。

使用场景：仅当项目需复用旧的Android.mk配置，或团队更熟悉Makefile语法时使用，新项目优先选择CMake。

如何在Android Studio中安装和配置NDK？

Android Studio提供了图形化的NDK安装与配置方式，无需手动下载解压，步骤清晰且兼容性更优，核心分为"安装NDK"和"项目配置NDK"两个环节，具体操作如下。

安装NDK（通过SDK Manager）

1、打开Android Studio，进入"Settings"（Windows：File → Settings，macOS：Android Studio → Settings）。
2、在左侧导航栏中找到"Appearance & Behavior → System Settings → Android SDK"，切换到"SDK Tools"选项卡。
3、勾选"NDK (Side by Side)"和"CMake"选项，点击版本下拉框选择需要安装的NDK版本（如26.1.10909125，即r26 LTS），CMake会自动匹配适配版本。
4、点击"Apply"或"OK"，在弹出的确认窗口中点击"OK"，Android Studio会自动下载并安装所选NDK和CMake，等待安装完成（需联网，视网络速度耗时5-30分钟）。
5、安装完成后，可在"SDK Location"中查看NDK安装路径（默认路径：Windows：C:\Users\用户名\AppData\Local\Android\Sdk\ndk\版本号，macOS/Linux：~/Library/Android/sdk/ndk/版本号）。

项目中配置NDK（两种核心场景）

场景一：新建项目时自动配置NDK

若创建支持NDK开发的新项目，Android Studio会自动关联已安装的NDK和CMake，无需手动配置。

1、打开Android Studio，点击"Start a new Android Studio project"。

2、在模板列表中选择"Native C++"，点击"Next"。

3、填写项目名称、包名、保存路径等信息，点击"Next"。

4、在"Cpp Standard"下拉框中选择C++标准（如C++17），勾选"Exceptions Support"（异常支持）和"Runtime Type Information Support"（运行时类型信息支持），点击"Finish"。

5、项目创建完成后，Android Studio会自动生成CMakeLists.txt（编译配置文件）和native-lib.cpp（原生代码示例），并在build.gradle中自动配置NDK和CMake路径。

场景二：现有项目手动配置NDK

若需为已存在的纯Java/Kotlin项目添加NDK支持，需手动在Gradle中配置NDK版本，步骤如下。

1、打开项目的"Module级build.gradle"文件（通常是app/build.gradle）。

2、在android闭包中添加ndkVersion和externalNativeBuild配置，指定NDK版本和CMake路径：

3、点击Sync Now，Gradle会自动同步NDK和CMake配置，若配置无误，同步成功，若提示"NDK not found"，需检查ndkVersion是否与安装的版本一致，或重新安装对应版本的NDK。

android {
    compileSdk 34 // 项目编译SDK版本，需与NDK兼容
    defaultConfig {
        applicationId "com.example.ndkdemo"
        minSdk 21 // 需 ≤ NDK最低支持API级别（如r26最低支持21）
        targetSdk 34
        versionCode 1
        versionName "1.0"
        // 配置原生构建参数
        externalNativeBuild {
            cmake {
                // 指定C++标准
                cppFlags '-std=c++17'
                // 指定目标CPU架构（可选，默认会编译所有支持的架构）
                abiFilters 'arm64-v8a', 'armeabi-v7a'
            }
        }
    }
    // 指定NDK版本（需与安装的版本一致）
    ndkVersion "26.1.10909125"
    // 配置CMake构建脚本路径
    externalNativeBuild {
        cmake {
            path file("src/main/cpp/CMakeLists.txt") // CMakeLists.txt的相对路径
            version "3.22.1" // CMake版本，需与安装的版本一致
        }
    }
}

如何在Windows 系统上配置NDK的环境变量？

配置NDK环境变量的核心目的是：让系统在任意目录下都能直接调用NDK的工具链（如ndk-build、clang），方便手动编译原生代码或使用命令行工具（如ndk-stack），不同系统的环境变量配置方式不同，以下是详细步骤，同时说明关键配置原理。

一、前提：获取NDK安装路径

首先确定NDK的安装路径，默认路径如下（若自定义安装，需替换为实际路径）：

Windows：C:\Users\你的用户名\AppData\Local\Android\Sdk\ndk\你的NDK版本号（如26.1.10909125）

验证路径正确性：进入该路径，若能看到ndk-build、toolchains、include等目录/文件，则路径正确。

二、Windows系统配置步骤（以Windows 10/11为例）

1、右键点击"此电脑" → 选择"属性" → 点击"高级系统设置" → 切换到"高级"选项卡 → 点击"环境变量"。
2、在"系统变量"区域，找到"Path"变量，点击"编辑"。
3、点击"新建"，粘贴NDK的安装路径（如C:\Users\ZhangSan\AppData\Local\Android\Sdk\ndk\26.1.10909125），点击"确定"。
4、（可选）若需使用ndk-build等工具，可再新建一个"NDK_ROOT"系统变量，变量值为NDK安装路径，后续可在脚本中通过%NDK_ROOT%引用路径，点击"确定"保存。
5、关闭所有已打开的命令行窗口（环境变量配置需重启命令行生效），打开新的命令提示符（CMD）或PowerShell。
6、验证配置：输入ndk-build --version或clang --version，若能输出对应的版本信息，则配置成功，若提示"不是内部或外部命令"，需检查路径是否正确，或重新配置环境变量。

如何创建一个支持NDK开发的Android项目？

创建支持NDK开发的项目核心是选择正确的模板、配置C++标准及原生构建参数，Android Studio提供了"Native C++"模板，可一键生成包含JNI交互、CMake配置的基础项目，步骤如下，同时解析项目结构与核心配置文件的作用：

一、新建项目步骤

1、打开Android Studio，点击"Start a new Android Studio project"（若已打开项目，点击File → New → New Project）。
2、在"Select a Project Template"页面，选择"Native C++"模板（位于"Phone and Tablet"分类下），点击"Next"。

3、项目基础信息配置：

Name：项目名称（如NDKDemo）。

Package name：应用包名（如com.example.ndkdemo），需符合Java包名规范。

Save location：项目保存路径，建议路径无空格和中文。

Language：选择Java或Kotlin（上层代码语言，不影响原生代码），推荐Kotlin。

Minimum SDK：选择项目最低支持的Android版本（如API 21，需与NDK最低支持API匹配），点击"Next"。
4、原生代码配置（关键步骤）：

Cpp Standard：选择C++标准，推荐"C++17"（兼容性与功能兼顾），若需兼容旧NDK版本，可选择"C++11"。

Exceptions Support：勾选（启用C++异常机制，避免原生代码抛出异常时崩溃）。

Runtime Type Information Support：勾选（启用运行时类型信息，支持dynamic_cast等C++特性）。

其他选项默认即可，点击"Finish"。

5、等待项目同步完成：Android Studio会自动下载依赖、配置CMake和NDK，同步成功后，项目结构自动生成。

二、项目核心结构解析（重点关注原生相关目录/文件）

三、核心文件作用与关键代码解析

1、native-lib.cpp（原生代码示例）

定义了供Java/Kotlin调用的原生函数，核心是JNI函数签名格式，代码如下。

关键说明：

extern "C" 用于指定C语言编译规则，避免C++名称修饰导致Java层无法找到该函数，JNIEnv* 是JNI环境指针，提供了Java与C++交互的核心接口，

jobject 是调用该方法的Java对象（此处为MainActivity实例）。

#include <jni.h>
#include <string>

// JNI函数签名格式：Java_包名_类名_方法名（包名中的.替换为_，类名含路径）
extern "C" JNIEXPORT jstring JNICALL
Java_com_example_ndkdemo_MainActivity_stringFromJNI(
        JNIEnv* env,
        jobject /* this */) {
    std::string hello = "Hello from C++";
    // 将C++字符串转换为jstring，返回给Java层
    return env->NewStringUTF(hello.c_str());
}

2、CMakeLists.txt（编译配置文件）

定义了原生代码的编译规则，核心是指定源文件、生成库名称、链接依赖等，代码如下。

# 指定CMake最低版本
cmake_minimum_required(VERSION 3.22.1)
# 定义项目名称（可自定义）
project("ndkdemo")
# 添加原生库：add_library(库名称 库类型 源文件路径)
# SHARED表示生成动态库（.so文件），STATIC表示静态库（.a文件）
add_library(
        ndkdemo
        SHARED
        native-lib.cpp)
# 查找系统库（此处查找日志库，用于原生代码输出日志）
find_library(
        log-lib
        log)
# 链接库：将生成的原生库与系统库/第三方库链接
target_link_libraries(
        ndkdemo
        ${log-lib})

3、MainActivity.kt（上层调用原生方法）

声明native方法，加载原生库，调用原生函数并显示结果，代码如下。

package com.example.ndkdemo

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.TextView
class MainActivity : AppCompatActivity() {
    // 加载原生库（库名称与CMakeLists.txt中定义的一致，即"ndkdemo"）
    init {
        System.loadLibrary("ndkdemo")
    }
    // 声明native方法（方法名与C++中JNI函数签名的方法名一致）
    external fun stringFromJNI(): String
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        // 调用native方法，获取C++返回的字符串并显示
        val tv: TextView = findViewById(R.id.sample_text)
        tv.text = stringFromJNI()
    }
}

如何在现有Android项目中集成NDK模块？

现有Android项目（纯Java/Kotlin）集成NDK模块，核心是"添加原生代码目录与文件""配置CMake/ndk-build编译规则""在Gradle中关联原生构建""实现Java与原生代码的JNI交互"，根据需求不同分为"集成自定义原生代码"和"集成预编译的.so库"两种场景，以下分别详解实操步骤与原理。

场景一：集成自定义原生代码（从零编写C/C++代码）

适用于需要开发新的原生功能（如自定义加密算法、高性能计算模块），步骤如下。

步骤一：创建原生代码目录与文件

1、在项目的app/src/main目录下，右键点击 → New → Directory，创建名为"cpp"的目录（用于存放C/C++代码）。

2、右键点击cpp目录 → New → C/C++ Source File，创建原生代码文件（如native-lib.cpp），选择"C++"类型，点击"OK"。

3、在native-lib.cpp中编写基础JNI函数（如返回字符串），确保函数签名格式正确。

场景二：集成预编译的.so库（复用现有原生库）