不能直接复制.so文件就完事，因为动态链接器依赖/etc/ld.so.cache缓存查找库，而该缓存仅收录符合命名规范、具备libhpdf.so→libhpdf.so.2.4→libhpdf.so.2.4.4三级符号链接结构的库，且必须执行sudo ldconfig刷新缓存才能生效。
为什么不能直接复制.so文件就完事
复制 libhpdf.so 到 /usr/local/lib 只是第一步。动态链接器（ld.so）不靠文件名找库，而是查 /etc/ld.so.cache —— 这个缓存由 ldconfig 生成，只扫描 /etc/ld.so.conf 及其包含的路径下的「符合命名规范」且「有正确符号链接结构」的库。如果只丢一个 libhpdf.so.2.4.4 进去，没建好 libhpdf.so 和 libhpdf.so.2.4 这两级符号链接，ldconfig 会忽略它，程序运行时仍报 error while loading shared libraries。
必须保证三类文件同时存在并链接正确
以 libhpdf 为例，/usr/local/lib 下应有：
-
libhpdf.so.2.4.4：真实库文件（主版本+次版本+修订号） -
libhpdf.so.2.4：指向.so.2.4.4的符号链接（ABI 兼容锚点） -
libhpdf.so：指向.so.2.4的符号链接（开发时链接用）
缺任意一个，或链接目标错位（比如 libhpdf.so.2.4 指向了 .so.2.3.1），都会导致编译失败或运行时崩溃。检查命令：ls -l /usr/local/lib/libhpdf.so*，确认输出中后两者都是 -> 形式。
复制后必须运行 ldconfig，且不能跳过 sudo
ldconfig 修改的是系统级缓存，必须用 sudo 才生效。常见错误包括：
- 漏掉
sudo，命令静默执行但缓存未更新 - 在非 root shell 中执行，提示
Permission denied却误以为成功 - 改了
/etc/ld.so.conf但忘了跑ldconfig（本例虽未修改 conf，但新库放入默认路径仍需刷新缓存）
验证是否生效：sudo ldconfig -p | grep hpdf。若无输出，说明没进缓存；若有，应看到类似 libhpdf.so (libc6,x86-64) => /usr/local/lib/libhpdf.so 的行。
头文件也要放对位置，否则编译通不过
库文件放对了，#include <hpdf.h></hpdf.h> 还是报错？因为编译器找不到头文件。标准做法是把头文件目录（如 hpdf/）整体复制到 /usr/local/include：
- 推荐方式：
sudo cp -r /path/to/hpdf/include/* /usr/local/include/（保持子目录结构） - 不推荐平铺：
sudo cp /path/to/hpdf/include/*.h /usr/local/include/，容易和系统头文件冲突 - 若头文件在
hpdf/子目录下，代码中必须写#include <hpdf></hpdf>，而非#include <hpdf.h></hpdf.h>
这步常被忽略，结果编译时报 fatal error: hpdf.h: No such file or directory，让人误以为库安装失败。
实际部署时最易卡在符号链接层级和 ldconfig 缓存刷新上，而不是复制动作本身。多看一眼 ls -l 输出和 ldconfig -p 结果，比重装十遍库更省时间。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
