so-name必须显式指定且仅含主版本号，version script控制符号导出，运行时需调用get_api_version校验版本；三者缺一不可，否则ABI兼容性无法保障。
so-name 必须显式指定，否则版本控制失效
不加 -Wl,-soname 编译出的 .so 文件在运行时会直接使用 real name（如 libfoo.so.1.2.3）查找，一旦文件名变动或路径调整，dlopen 或程序启动就报 cannot open shared object file。系统无法通过 ldconfig 建立版本映射，也就谈不上兼容性管理。
正确做法是编译时强制绑定 so-name：
gcc -shared -fPIC -Wl,-soname,libfoo.so.1 -o libfoo.so.1.2.3 foo.o
这样生成的库 ELF 头中会记录 SONAME: libfoo.so.1，后续所有依赖它的可执行文件都会嵌入这个名称，而不是具体路径或完整版本号。
-
libfoo.so.1是运行时链接器实际查找的名字，也是ldconfig创建软链的目标 -
libfoo.so.1.2.3是磁盘上真实存在的文件（real name），可带补丁号 - 绝不允许让 so-name 包含
.2或.2.3—— 那意味着次版本升级就要破坏 ABI
版本号语义必须与 ABI 变更严格对齐
Linux 动态库的 .so.x 中的 x 就是主版本号（MAJOR），它不是“第几个发布版”，而是 ABI 兼容性的唯一标识。只要函数签名、结构体布局、全局变量定义发生任何不兼容变更，就必须升主版本。
常见误操作：
- 把
libbar.so.1.0.0升级成libbar.so.1.1.0，但悄悄改了struct config的字段顺序 → 运行时崩溃，因为旧程序仍按老偏移读内存 - 只加了个新函数，却把 so-name 改成
libbar.so.2→ 旧程序无法加载，哪怕它根本没调用新函数 - 修复一个空指针 crash，但没改接口，却发布为
libbar.so.1.0.1→ 合理，但需确保 real name 中的.1和.0.1不参与运行时解析
真正起作用的只有 so-name 的主版本数字。次版本（MINOR）和修订号（PATCH）只用于人工识别和部署管理，ld-linux.so 完全不解析它们。
符号版本脚本（version script）不是可选，而是 ABI 封装刚需
仅靠 so-name 只能控制“加载哪个库文件”，不能防止旧程序误调新符号、或新程序意外依赖旧符号实现。真正的符号级兼容必须靠 --version-script。
比如你新增了线程安全版 process_data_mt，但不想让旧程序链接到它（避免隐式依赖新行为），就得写脚本：
LIBFOO_1.0 {
global:
init;
process_data;
local:
*;
};
LIBFOO_1.1 {
global:
process_data_mt;
} LIBFOO_1.0;
编译命令：
gcc -shared -fPIC -Wl,--version-script=libfoo.map -o libfoo.so.1.1.0 foo.o
关键点：
- 旧程序链接时若未声明版本，默认绑定
LIBFOO_1.0节点下的符号 - 新程序可用
process_data_mt@LIBFOO_1.1显式请求新版符号 -
local: *隐藏所有未列名符号，避免内部函数被意外调用 - 没有 version script，所有符号默认属于基础版本，等于放弃符号粒度控制
运行时验证不能省，dlopen 后必须检查 get_api_version
so-name 和 version script 解决的是“能不能加载”，但不保证“加载后能不能用”。例如：你发布了 libfoo.so.1.2.0，so-name 是 libfoo.so.1，也写了 version script，但某个关键函数内部逻辑重构导致返回值语义变化——旧程序仍能加载，却得到错误结果。
因此，每个动态库应导出一个 C 风格的版本查询函数：
extern "C" const char* get_api_version() { return "1.2.0"; }
调用方在 dlopen 后立刻做校验：
void* h = dlopen("libfoo.so.1", RTLD_NOW);
if (!h) { /* handle error */ }
auto ver_fn = (const char*(*)())dlsym(h, "get_api_version");
const char* ver = ver_fn ? ver_fn() : "0.0.0";
if (strcmp(ver, "1.2.0") != 0 && strcmp(ver, "1.2.1") != 0) {
dlclose(h);
// 拒绝使用，避免静默错误
}
这步看似冗余，但在混合部署、容器镜像复用、CI/CD 自动发布等场景中，是最后一道防线。很多线上事故就源于跳过了这个检查。
最易被忽略的是：version script 控制符号导出，但 get_api_version 必须显式列入 global: 列表，否则 dlsym 找不到它——这种细节一漏，整套版本机制就形同虚设。
