Poppler C++ API 初始化失败主因是混用 libpoppler-cpp 与 libpoppler-glib；应仅链接 -lpoppler-cpp、安装 libpoppler-cpp-dev，并用 pkg-config --libs poppler-cpp 验证路径。
Poppler C++ API 初始化失败：找不到 libpoppler-glib.so 或符号未定义
直接链接 libpoppler-glib 但运行时报 libpoppler-glib.so.8: cannot open shared object file，或编译时提示 undefined reference to poppler_document_new_from_file，本质是链接顺序和依赖链没理清。Poppler 的 C++ 封装（libpoppler-cpp）和 GObject 封装（libpoppler-glib）是两套独立 ABI，混用必崩。
- 只用 C++ API：链接
-lpoppler-cpp，**不要**连-lpoppler-glib；头文件只 include<poppler/cpp/poppler-document.h> - 确认开发包已安装：Ubuntu/Debian 上运行
sudo apt install libpoppler-cpp-dev（不是libpoppler-glib-dev） - 检查实际库路径：
pkg-config --libs poppler-cpp应输出类似-L/usr/lib/x86_64-linux-gnu -lpoppler-cpp；若为空，说明 pkg-config 文件缺失，需手动指定-L和-l
读取 PDF 文本内容：Document → Page → TextPage 流程卡在空指针
poppler::document::load_from_file() 成功后，get_page(0) 返回 nullptr，常见于 PDF 加密或损坏，但更大概率是页码越界——Poppler 页索引从 0 开始，而 get_pages() 返回的是总页数，不是最大索引。
- 先检查文档是否有效：
if (!doc) { /* 处理加载失败 */ }，错误通常来自路径错误或权限不足 - 安全取页写法：
auto page = doc->get_page(0); if (!page) { /* 页不存在，可能是空 PDF 或加密 */ } - 提取文本必须经
text_page中转：auto text_page = page->create_text_page(); if (text_page) { std::string txt = text_page->text(); }；跳过create_text_page()直接调page->text()会编译失败 - 注意编码：返回的
std::string是 UTF-8，含 Unicode 字符（如中文），别用char*逐字节处理
解析出的文本乱序、缺字或位置错乱
Poppler 的 text_page->text() 返回的是按渲染顺序拼接的字符串，不保证逻辑阅读顺序；对多栏、图文混排 PDF，结果常不可读。这不是 bug，而是底层设计使然——它忠实还原绘制指令流，而非语义结构。
- 需要结构化文本时，改用
text_page->get_selection()配合坐标范围筛选，或遍历text_page->get_char_info_list()手动排序 - 避免依赖默认
text()：它等价于把所有字符按绘制顺序 concat，遇到换行、空格压缩、字体替换时极易失真 - 性能代价：生成
text_page是 CPU 密集型操作，大 PDF 单页可能耗时数百毫秒；缓存text_page实例，勿重复创建
中文显示为方块或乱码：字体映射失败
即使文本提取成功，控制台打印仍是 或空格，问题不在 Poppler 解析，而在终端/IDE 不支持 UTF-8 渲染，或字体缺失。Poppler 本身不负责字体渲染，只提取已嵌入的字形 ID 和 Unicode 映射。
立即学习“C++免费学习笔记（深入）”；
- 验证文本真实内容：
std::cout 看首字节是否为 UTF-8 多字节序列（如中文「你」是 <code>e4 bd<a0></a0>） - Linux 终端确保
locale含UTF-8（如zh_CN.UTF-8），并安装中文字体（fonts-wqy-microhei） - 调试时写入文件比终端输出更可靠：
std::ofstream f("out.txt"); f ，再用支持 UTF-8 的编辑器打开
实际项目里最常卡住的不是代码写法，而是误以为 Poppler 能像 OCR 那样“理解”版面——它只是忠实导出 PDF 指令流里的文本片段。真正要处理扫描件、复杂排版或手写体，得接 Tesseract 或 Adobe PDF Services。
