必须调用hpdf_new初始化hpdf_doc对象，否则程序崩溃或生成无效pdf；需检查返回值非null，中文需加载.ttf字体并指定unicode编码，页面与字体操作须严格按序执行。
libharu创建PDF文件前必须初始化HPDF_Doc
不调用 HPDF_New 或调用失败就直接操作，程序大概率崩溃或产生无效PDF。libharu不是“拿来即写”，它依赖显式文档对象管理生命周期。
常见错误现象：Segmentation fault、HPDF_INVALID_DOCUMENT 错误、生成的PDF打不开（实际是空文件或损坏头）。
- 务必检查
HPDF_New返回值是否非 NULL，NULL 表示内存分配失败或库未正确加载 - 若需自定义内存管理器，传入的
error_handler和mem_handler必须有效，否则后续所有调用都不可靠 - Windows 下若链接静态版 libharu，需确保
HARU_STATIC宏已定义，否则HPDF_New可能因符号导出问题返回 NULL
写入文本前要先创建页面并设置字体
libharu 不允许在无页面上下文下调用 HPDF_Page_BeginText；字体未载入就调用 HPDF_Page_SetFontAndSize 会静默失败，后续 HPDF_Page_ShowText 什么也不显示。
使用场景：中文内容需额外处理——libharu 自带字体仅支持 Latin-1，中文必须用 HPDF_LoadTTFontFromFile 加载 .ttf 文件，并指定 Unicode 编码（HPDF_PAGE_ENCODING_UNICODE）。
- 页面创建后必须调用
HPDF_Page_EndText配对，否则文本不会渲染 - 字体路径必须是绝对路径或相对于当前工作目录的有效路径；相对路径在 IDE 中运行常因 cwd 不一致而失败
- Linux/macOS 下注意字体文件权限，
HPDF_LoadTTFontFromFile失败时返回HPDF_INVALID_FONT，但不报错信息，建议用HPDF_GetError检查
保存文件前记得释放资源并检查错误
HPDF_SaveToFile 成功只表示写入完成，不代表 PDF 结构合法；很多“空白PDF”问题源于没调用 HPDF_Free 前就退出，导致缓冲区未刷盘或内存未清理。
性能影响：大文件（>10MB）下，频繁调用 HPDF_Page_MoveTo + HPDF_Page_LineTo 绘图比批量用 HPDF_Page_CurveTo 慢数倍；但更关键的是——不调用 HPDF_Free 会导致进程残留句柄，多次运行后可能耗尽系统资源。
-
HPDF_SaveToFile返回HPDF_OK后，仍建议用系统命令如file output.pdf或打开验证内容是否真实写入 - 若需流式输出（如 HTTP 响应），改用
HPDF_Stream+HPDF_SetStream，而非强行截取文件内容 - 多线程环境下，每个
HPDF_Doc实例必须独占，libharu 不是线程安全的——共用一个 doc 对象会引发随机崩溃
编译链接时容易漏掉依赖项
libharu 本身依赖 zlib 和 libpng（即使只生成纯文本 PDF），链接时缺任何一个，HPDF_New 都可能返回 NULL，且错误提示为 “out of memory” 这类误导信息。
典型错误：CMakeLists.txt 里只写了 target_link_libraries(myapp haru)，但没加 z 和 png，结果 Linux 下运行时报 undefined symbol: inflate。
- pkg-config 可靠性高：
pkg-config --libs --cflags libharu能自动补全 zlib/png 路径和宏定义 - macOS 上若用 Homebrew 安装 libharu，注意它默认链接系统 zlib，但若项目自己编译了 zlib，需确保版本兼容（libharu 2.3.x 需 zlib ≥1.2.11）
- Windows MinGW 用户常忽略
-lz -lpng，或顺序写反（必须 zlib 在 png 前），否则链接失败
HPDF_GetFont 获取返回的 HPDF_Font 对象，再传给 HPDF_Page_SetFontAndSize —— 直接传文件路径进去是无效的。这个接口设计反直觉，但绕不过。C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
