std::unique_ptr 是最稳的 pimpl 实现方式，头文件仅前向声明 impl 并声明 unique_ptr 成员，impl 定义及依赖全移至 .cpp；析构函数必须在 .cpp 中定义以避免 incomplete type 错误；拷贝需显式深拷贝，移动可 default；适用于接口稳定、实现多变场景，不适用于性能敏感小对象。
std::unique_ptr 是最稳的 Pimpl 实现方式
直接用 std::unique_ptr<impl></impl> 持有前向声明的实现类，是现代 C++ 项目中降低编译依赖最可靠的选择。它天然支持异常安全、自动析构，且语义清晰——谁创建谁销毁，不引入共享语义干扰。
关键点在于：头文件里只写 class Impl; 和 std::unique_ptr<impl> pImpl;</impl>，所有 Impl 的定义、成员变量、所用类型（比如 std::unordered_map、QPixmap、自定义类）全部挪到 .cpp 文件里。这样，哪怕 Impl 里包含 Qt 或 Boost 头文件，也不会污染公有接口。
- 别用裸指针：
Impl*需手动管理生命周期，容易漏delete或引发异常安全问题 - 慎用
std::shared_ptr：控制块构造仍需Impl完整定义，析构位置要求和unique_ptr一样严格 - 不能把
Impl定义在头文件里——哪怕加了private或anonymous namespace，只要暴露了类型，就等于暴露了它所依赖的所有头文件
必须在 .cpp 中定义析构函数
这是最容易翻车的地方：std::unique_ptr<impl></impl> 在析构时要调用 Impl 的析构函数，因此需要知道 Impl 的完整布局。而头文件里只有前向声明，sizeof(Impl) 是未知的。
如果在头文件里写 ~Widget() = default;，每个包含该头的翻译单元都会尝试生成析构逻辑，但此时根本没见过 Impl 的定义，编译器会报错：error: invalid application of 'sizeof' to incomplete type 'Widget::Impl'。
- 头文件中只声明：
~Widget();（不带实现） -
.cpp文件中，在Impl结构体定义之后，再写Widget::~Widget() = default;或空实现{} - 绝对不要在头文件里内联析构函数，哪怕它看起来“什么都没做”
拷贝和移动语义必须手动控制
std::unique_ptr 默认禁用拷贝，所以 Widget 的拷贝构造/赋值函数天然被删除。这不是缺陷，而是信号：Pimpl 的设计本意就是让你明确决定“是否允许拷贝”以及“如何拷贝”。
若真需要拷贝语义：
- 拷贝必须深拷贝：
pImpl = std::make_unique<impl>(*other.pImpl);</impl>，前提是Impl自身可拷贝 - 移动构造/赋值可以
= default，但必须定义在.cpp文件中 —— 因为它们隐式调用Impl的移动操作，同样需要完整类型 - 别用模板或宏自动推导拷贝逻辑；Pimpl 的价值之一，就是把“怎么拷”这个决策留在实现侧，不让头文件承担语义负担
注意间接访问开销与 ABI 稳定性边界
Pimpl 带来一层指针跳转，每次访问私有数据都要解引用一次。对高频调用路径（如循环体内、数学计算核心），这可能成为瓶颈。不是所有类都适合 Pimpl。
更隐蔽的问题是 ABI 稳定性：一旦你对外暴露了 Widget 的对象布局（比如把它作为 DLL 导出类的成员、或放入 std::vector<widget></widget>），就不能再改 Widget 的大小——而 std::unique_ptr<impl></impl> 固定为一个指针宽（通常 8 字节），这点反而是优势。
- 优先用于接口稳定、实现常变的模块（如跨平台封装、配置解析器、日志后端）
- 避免用于性能敏感的小对象（如
Vec2、Color），那里内联和栈布局更重要 - 若要导出为二进制接口（如 SDK），确保
Widget构造/析构/拷贝全部定义在.cpp中，且不依赖内联实现
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
