C++ ABI 天然不稳定，因标准不规定 sizeof(std::string)、虚表布局、name mangling 等细节，不同编译器或库版本会导致二进制不兼容；PIMPL、禁用模板/STL 导出、C 接口封装是有效应对策略。
为什么 C++ 的 ABI 天然不稳定
C++ 标准不规定 ABI，sizeof(std::string)、std::vector<T>::iterator 是否是原生指针、虚函数表布局、name mangling 规则，全由编译器和标准库实现决定。同一份代码用 gcc 11 和 clang 16 编译，或链接不同版本的 libstdc++，都可能产生二进制不兼容。
用 PIMPL 模式隔离实现细节
暴露给用户的头文件里，只保留纯接口类（无虚函数、无模板、无 STL 成员），所有实现细节通过指针隐藏。这是控制 ABI 稳定最有效且可落地的手段。
- 用户头文件中定义
class Widget，仅含public构造/析构/简单成员函数，内部用std::unique_ptr<WidgetImpl>持有实现 -
WidgetImpl定义在单独的.cpp文件里，可自由使用std::vector、std::shared_ptr、模板、新 C++ 特性，不影响头文件 ABI - 析构函数必须在
.cpp中显式定义（哪怕为空），否则编译器可能把内联析构逻辑塞进用户代码，导致WidgetImpl布局变化时崩溃
class Widget {
public:
Widget();
~Widget(); // 必须在 .cpp 中定义
void set_name(const char* n);
private:
class WidgetImpl;
std::unique_ptr<WidgetImpl> pimpl_;
};避免导出模板、STL 类型和内联函数
任何被导出的符号若依赖模板实例化或 STL 内部布局，就等于把编译器私有 ABI 暴露给了用户。即使你用的是 libstdc++，升级到新版本后 std::string 的小字符串优化阈值也可能从 15 字节变成 22 字节，直接破坏二进制兼容。
- 不要在头文件中写
extern template class std::vector<int>;并试图导出它 - 不要把
std::string、std::optional<T>作为函数参数或返回值出现在导出接口中；改用const char*、void*、自定义 POD 结构体 - 所有导出函数禁止
inline，包括constexpr函数（除非确定其展开结果不会随标准库变更而变） - 使用
__attribute__((visibility("hidden")))（GCC/Clang）或__declspec(dllexport)（MSVC）精确控制哪些符号真正导出，避免意外泄漏实现符号
用稳定 ABI 的 C 接口做底层桥梁
如果对稳定性要求极高（如系统级 SDK、跨语言调用、长期维护的插件架构），直接放弃 C++ ABI，用 C 接口封装核心能力。C ABI 是操作系统级约定，int 就是 4 字节（LP64 下），struct 布局由 ABI 文档明确定义，几乎不随编译器版本漂移。
立即学习“C++免费学习笔记（深入）”；
- 提供
widget_create()、widget_set_name(widget_t*, const char*)等纯 C 函数，所有参数/返回值为基本类型或 opaque 指针 - C++ 实现层在内部做转换：比如把
const char*复制进std::string，但用户完全感知不到 - 头文件用
#ifdef __cplusplus包裹extern "C"，确保 C++ 用户也能安全调用
extern "C" {
typedef struct widget_s widget_t;
<p>widget_t<em> widget_create(void);
void widget_destroy(widget_t</em>);
void widget_set_name(widget_t<em>, const char</em> name);
}C++ ABI 稳定性不是靠“写得规范”就能保证的，而是靠主动放弃一部分语言便利性来换取可控性。最容易被忽略的一点是：只要头文件里出现了任何标准库容器的成员变量或函数签名，你就已经放弃了 ABI 稳定承诺——哪怕当时没出问题，下次升级 libc++ 就可能触发段错误。
