Android NDK链接静态库 .cpp定义函数报未定义引用错误

问题表现 #

• 静态库内函数拆分到独立.cpp文件实现时，项目构建失败，Main.cpp调用位置触发undefined reference to 'FunctionName()'错误，clang++返回linker command failed with exit code 1；即使对应.cpp显示已完成编译，依然提示找不到函数定义
• 函数在头文件内以类内联方式实现时，项目可正常编译运行
• 排查过程中额外报错：相关目标文件不是ELF对象

复现代码 #

报错场景 #

Example.h

void example();

Example.cpp

void example()
{
} // 触发链接错误

正常运行场景 #

Example.h

class example
{
public:
  void example()
  {

  } // 可正常编译运行
}

根因说明 #

两个报错是直接关联的：

1. 目标文件不是ELF对象是核心诱因：编译静态库.cpp时使用了主机端编译器（Windows下MSVC、Mac下本地clang、Linux下本地g++等），生成的是主机架构的目标文件，不符合Android系统要求的对应ABI（arm64-v8a/armeabi-v7a/x86_64等）ELF格式。NDK链接器处理静态库时会直接跳过格式不合法的目标文件，不会将其中的函数符号纳入链接流程，最终触发符号找不到的错误。
2. 头文件内联实现可正常运行的原因：类内联函数会在引用它的Main.cpp编译阶段直接展开代码，编译进Main.cpp对应的Android架构目标文件中，不需要从预编译的静态库中查找符号，因此不会触发链接错误。

修复步骤 #

• 编译静态库所有.cpp文件时，必须使用Android NDK自带的、与项目目标ABI匹配的clang/clang++编译器，禁止使用系统默认的本地编译器。
• 优先将静态库的编译逻辑纳入Android项目的NDK CMake构建体系，不要提前单独预编译静态库再手动导入，从根源避免编译器选型、ABI匹配错误。
• 若必须使用预编译静态库，导入时需在CMake或build.gradle配置中明确指定静态库对应的目标ABI，与项目编译ABI完全一致；可使用NDK自带的llvm-readelf工具检查静态库内.o、.a文件的架构，确认是对应Android ABI的ELF格式。
• 检查静态库链接顺序：C++链接器按顺序解析符号，被依赖的静态库要放在引用方的后面，避免顺序错误导致符号解析失败。

内容的提问来源于stack exchange，提问作者user12826193