Aspose.PDF FOSS
C++
Troubleshooting

Troubleshooting

构建因 C++20 错误而失败

Aspose.PDF FOSS for C++ 需要 C++20 编译器 — clang 16+、gcc 13+，或 MSVC 2022 17.5+。如果你的构建出现诸如 “designated initializers only allowed in C++20” 或 “concepts require ‘-std=c++20’” 的错误，则说明使用该库的项目未启用 C++20 标准进行编译。

在将库添加为子目录之前显式设置标准：

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

在命令行中这对应于 -std=c++20（clang/gcc）或 /std:c++20（MSVC）。

CMake 配置失败 — 版本过旧

项目需要 CMake 3.22 或更高版本。使用旧版 CMake 会产生类似以下的错误：

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.22 or higher is required.  You are running version 3.16.3

检查已安装的版本并进行升级，而不是编辑已供应的 CMakeLists.txt：

cmake --version

从以下位置安装当前版本 cmake.org 或使用您的软件包管理器 — 最低版本反映了生成器和语言特性，构建实际使用的版本，而非随意设定的底线。

FetchContent 下载仓库失败

如果您使用 FetchContent 而不是手动 add_subdirectory 来供应库，配置时的失败通常是网络问题，而不是 CMake 问题：

include(FetchContent)
FetchContent_Declare(
    aspose_pdf_foss
    GIT_REPOSITORY https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(aspose_pdf_foss)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

FetchContent_MakeAvailable 在 CMake 配置期间运行 git clone。在公司代理或防火墙后，或在隔离的 CI 运行器上，这会因 Failed to clone repository 而失败。解决方法如下：

  • 为 CMake 配置步骤设置 HTTPS_PROXY/HTTP_PROXY，或
  • 预先克隆一次仓库并将 FETCHCONTENT_SOURCE_DIR_ASPOSE_PDF_FOSS 指向本地检出，以便 FetchContent 重用它而不是通过网络获取，或
  • 直接供应源码并使用 add_subdirectory()，它在配置时没有网络依赖。

链接时未定义引用 / 未解析的外部符号

编译成功，但链接时出现 undefined reference to Aspose::Pdf::Document::...（gcc/clang）或 unresolved external symbol 错误（MSVC）。这几乎总是由以下两种原因之一导致：

  1. 缺少链接步骤 — target_link_libraries(your_app PRIVATE aspose_pdf_foss) 缺失或拼写错误。 add_subdirectory() 单独使用只会让头文件可见；它并不会链接静态库。
  2. MSVC 上的运行时库 / 构建类型不匹配 — 链接 a Release-已构建 aspose_pdf_foss.lib 转换为 Debug 可执行文件（或反之）混合不兼容的 C 运行时库并导致 LNK2038 不匹配。请使用相同的 CMAKE_BUILD_TYPE （或相同的 /MD//MDd 运行时库设置）。

XMP 元数据类型检查始终返回 false

XmpValue —— 从 Document.Metadata() 条目返回的值类型 —— 提供类型检查助手 IsDateTime()、IsField()、IsNamedValue()、IsRaw()、IsNamedValues() 与 IsStructure()。在当前版本中，这六个方法都是存根，始终返回 false，因此依据它们来区分 XMP 值种类的代码总是走“false”路径。

请改用已实现的检查 — IsString()、IsInteger()、IsDouble()、IsArray() — 或在已从上下文中得知值的种类时直接调用相应的访问器（ToStringValue()、ToInteger()、ToDouble()、ToArray()）。少数低层内部类型（BitmapInfo 的默认构造函数，以及 PDF 对象模型使用的内部 Encoding 和 Value 类型）也包含未在典型文档处理代码中被调用的存根实现。

另请参阅

 中文