minSdk 与新 API 闸门：为什么编译通过不代表低版本设备能运行
Android 新版本会不断给 NDK 增加 API。问题是：你的 App 可能要运行在旧设备上。于是就出现一个很容易误解的现象：代码能编译，不代表所有设备都能运行。
这一篇讲清楚 minSdkVersion、ANDROID_PLATFORM、新 API、dlopen/dlsym 之间的关系。
先理解两个时间点
NDK API 有两个时间点。
编译时：你的电脑上有没有这个头文件和符号声明
运行时：用户手机系统里有没有这个真实实现
编译时通过，只说明“工具链认识这个名字”。运行时能不能用，要看设备系统版本。
这就像你写菜单时看到了“新品咖啡”，但用户所在门店未必真的有这款咖啡。
minSdkVersion 管什么
minSdkVersion 表示你的 App 声明支持的最低 Android 版本。
对 NDK 来说，官方文档说明：NDK API 可用性由 minSdkVersion 管理。比 minSdkVersion 更新的 API，默认不能直接调用，应该使用 dlopen/dlsym 或弱 API 引用等方式。
例如：
minSdkVersion = 23
你直接调用 API 29 才出现的 native 函数
API 23 设备没有这个符号
运行时可能 dlopen 失败
ANDROID_PLATFORM 管什么
CMake 里常见：
-DANDROID_PLATFORM=android-23
它告诉 NDK：这份 native 库最低要按 API 23 的可用能力构建。
如果设置太高，低版本设备无法运行。官方 CMake 文档也提醒，NDK 库不能运行在低于 ANDROID_PLATFORM 的设备上。
新 API 的正确使用姿势
假设某个函数只在 API 26+ 可用，而你的 minSdk 是 23。
错误姿势：
void useNewFeature() {
NewApiFunction();
}
正确思路：
先判断系统版本或符号是否存在
存在就走增强路径
不存在就走基础路径
使用 dlopen 和 dlsym
dlopen 打开动态库。
dlsym 查找符号地址。
#include <dlfcn.h>
using NewApiFn = int (*)(int);
class NewApiGate {
public:
bool load() {
handle_ = dlopen("libandroid.so", RTLD_NOW);
if (handle_ == nullptr) {
return false;
}
fn_ = reinterpret_cast<NewApiFn>(dlsym(handle_, "NewApiFunction"));
return fn_ != nullptr;
}
bool available() const {
return fn_ != nullptr;
}
int call(int value) const {
return fn_(value);
}
~NewApiGate() {
if (handle_ != nullptr) {
dlclose(handle_);
}
}
private:
void* handle_ = nullptr;
NewApiFn fn_ = nullptr;
};
这段代码表达的是“运行时探测”。它不是靠猜系统版本，而是直接问系统：这个符号在不在。
为什么要有降级路径
运行时探测如果失败，不能直接崩溃，要有基础路径。
if (gate.available()) {
useHighVersionFeature();
} else {
useCompatibleFeature();
}
例如播放器中可以这样设计。
高版本：使用更精细的渲染时间回调
低版本：使用保守 sleep + releaseOutputBuffer
这让同一份 App 能在新设备上更好，在旧设备上至少稳定。
弱 API 引用是什么
官方“Using newer APIs”文档还介绍了 weak API references。它允许编译器把新 API 符号作为弱引用处理，运行时不存在时不会立刻导致装载失败。
对初学者来说，先掌握 dlopen/dlsym 的思路更直观。等项目需要大量新 API 闸门，再评估弱引用方案。
不要只靠 Build.VERSION
Kotlin 层可以判断：
if (Build.VERSION.SDK_INT >= 26) {
nativeEnableNewFeature()
}
但 native 层仍应有自己的保护。因为 native 库可能被不同入口调用，单靠 UI 层判断很脆弱。
工程上建议：
Kotlin 层做用户体验分流
native 层做最后安全闸门
本章实验
设计一个能力探测对象，启动时输出：
api_gate: feature_x available=true
api_gate: feature_y available=false fallback=basic_path
再在低 API 模拟器上运行，确认：
App 不在 System.loadLibrary 阶段崩溃
新 API 不存在时走降级路径
日志能明确说明降级原因
工程风险与观测
新 API 最大的风险是“编译期自信，运行时崩溃”。所以每个新能力都应该有一条观测日志。
feature=FrameRenderedCallback api=33 available=true path=enhanced
feature=FrameRenderedCallback api=23 available=false path=fallback
这条日志的价值在于：低版本设备出问题时，你能确认它到底走了增强路径还是降级路径。
发布前审计时，把新 API 列成表。
API 名称
首次可用版本
项目 minSdk
是否有 dlsym 或 weak reference
是否有降级路径
低版本测试是否通过
如果一个新 API 没有降级路径，它就不是“优化项”，而是兼容性阻断项。
本章结论
NDK 兼容性要区分编译时和运行时。minSdkVersion 是最低承诺，ANDROID_PLATFORM 是 native 构建闸门，新 API 要通过运行时探测和降级路径纳入设计。真正稳定的 native 模块，不能把“我这里编译过了”当成兼容性证明。