QXlsx 项目集成指南：CMake 安装、find_package 链接与免安装嵌入的三种实战方案

发布时间：2026/10/6 5:52:17

QXlsx 项目集成指南：CMake 安装、find_package 链接与免安装嵌入的三种实战方案
数据分析【免费下载链接】QXlsxExcel file(*.xlsx) reader/writer library using Qt. Descendant of QtXlsxWriter.项目地址https://gitcode.com/gh_mirrors/qx/QXlsx点击查看免费下载QXlsx 是基于 Qt 的 Excel.xlsx读写库QtXlsxWriter 的后继项目。本文以仓库根目录下的 HowToSetProject-cmake.md 为骨架结合 QXlsx/CMakeLists.txt 及仓库内多个示例工程的真实配置完整讲解三种 CMake 集成路径全局安装后 find_package、add_subdirectory 子目录方式、FetchContent 远程拉取方式。读完本文你将能在自己的 Qt 5 / Qt 6 工程中正确配置、构建并链接 QXlsx并理解其包导出与版本探测的底层机制。一、三种集成方式速览QXlsx 的 CMake 集成整体上分为安装使用与免安装使用两大类其中免安装又细分为子目录与 FetchContent 两种。三种方式最终都归结为同一件事让 CMake 找到QXlsx::QXlsx这个 target 并完成链接。方式命令 / 关键代码适用场景是否需安装安装 find_packagecmake --install .后find_package(QXlsxQt5/QXlsxQt6)多工程复用、系统级安装、二进制分发是add_subdirectoryadd_subdirectory(QXlsx)与 QXlsx 源码同仓开发、快速验证否FetchContentFetchContent_Declare(...)构建时自动下载指定版本源码否无论采用哪种方式应用侧链接代码完全一致target_link_libraries(myapp PRIVATE QXlsx::QXlsx)QXlsx::QXlsx是 QXlsx 通过两处机制提供的目标名一是库自身定义的 ALIAS 目标见 QXlsx/CMakeLists.txt 的add_library(QXlsx::QXlsx ALIAS QXlsx)二是安装时导出 targets 文件所用的NAMESPACE QXlsx::见同文件 L211-L216二者保证了源码嵌入与安装后两种场景下链接名一致。二、方案一完整安装 QXlsxfind_package 的前置步骤官方文档给出的安装流程如下mkdir build cd build cmake ../QXlsx/ -DCMAKE_INSTALL_PREFIX... -DCMAKE_BUILD_TYPERelease cmake --build . cmake --install .各步骤要点-DCMAKE_INSTALL_PREFIX...指定安装前缀缺省时使用 CMake 默认前缀Unix 系为/usr/local。建议显式指定便于后续find_package定位或卸载。-DCMAKE_BUILD_TYPERelease配置为 Release 构建也可省略在构建时通过--config Release指定多配置生成器如 Visual Studio 需要后者。cmake --build .等价于make执行编译。cmake --install .执行安装产物由 QXlsx/CMakeLists.txt 中的 install 规则决定。从安装规则看安装产物包括库文件安装到${CMAKE_INSTALL_LIBDIR}lib或lib64公共头文件header/下全部xlsx*.h公共头安装到${CMAKE_INSTALL_INCLUDEDIR}/QXlsx其中PUBLIC_HEADER列表在 QXlsx/CMakeLists.txt#L120-L140 显式声明CMake 包配置文件QXlsxQt5Config.cmake、QXlsxQt5ConfigVersion.cmake与QXlsxQt5Targets.cmake安装到${CMAKE_INSTALL_LIBDIR}/cmake/QXlsxQt5Qt 6 同理对应QXlsxQt6*。这些配置文件由 cmake/modules/qxlsx-config.cmake.in 与 cmake/modules/qxlsx-config-version.cmake.in 两个模板通过configure_package_config_file/configure_file生成。其中版本文件实现了标准的版本兼容判定当请求版本不高于安装版本时返回PACKAGE_VERSION_COMPATIBLE精确相等时置PACKAGE_VERSION_EXACT请求版本更高时标记PACKAGE_VERSION_UNSUITABLE并打印VERSION CHECK FAILED提示。当前 QXlsx 项目版本为 1.5.1见 QXlsx/CMakeLists.txt#L5-L8。三、方案二在应用工程中通过 find_package 使用安装完成后在你的CMakeLists.txt中写入find_package(QXlsxQt5 REQUIRED) # or QXlsxQt6 target_link_libraries(myapp PRIVATE QXlsx::QXlsx)3.1 为什么包名是 QXlsxQt5 / QXlsxQt6包名与构建时所用 Qt 主版本绑定。QXlsx 的 CMake 将导出名设置为QXlsxQt${QT_VERSION_MAJOR}见 QXlsx/CMakeLists.txt#L26因此用 Qt 5 构建安装后find_package(QXlsxQt5 REQUIRED)用 Qt 6 构建安装后find_package(QXlsxQt6 REQUIRED)。3.2 Qt 主版本自动探测与强制指定如果构建 QXlsx 时没有预先定义QT_VERSION_MAJORQXlsx 的 CMakeLists 会自行探测可用版本if(NOT DEFINED QT_VERSION_MAJOR) find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui REQUIRED) endif() find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui REQUIRED)见 QXlsx/CMakeLists.txt#L17-L20。该写法是 Qt 官方推荐的双版本探测模式先按Qt6、Qt5的优先顺序探测探测成功后QT_VERSION_MAJOR被自动赋值随后按该主版本查找对应组件。注意探测优先顺序为Qt6 优先于 Qt5——如果你的机器同时装了 Qt 5 与 Qt 6 而未指定将默认选用 Qt 6。需要强制指定时在配置命令中追加cmake ../QXlsx/ -DQT_VERSION_MAJOR5 # 强制 Qt 5或在应用工程add_subdirectory之前设置缓存变量例如仓库中 ExcelViewer/CMakeLists.txt#L13-L14 的写法# Tell QXlsx which Qt major version to use. set(QT_VERSION_MAJOR 6)3.3 与 Qt 版本绑定的其他构建细节Qt 版本不仅决定包名还影响编译标准与依赖C 标准Qt 6 构建使用 C17Qt 5 构建使用 C11见 QXlsx/CMakeLists.txt#L28-L32且库对外声明INTERFACE cxx_std_11L177Qt 6.10 特例当Qt6Gui_VERSION 6.10.0时需要额外find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)L22-L24实际上库始终链接Qt${QT_VERSION_MAJOR}::GuiPrivateL183-L186因为 QXlsx 内部使用了 Qt 私有头文件包含路径构建期内包含header/目录安装后引用${CMAKE_INSTALL_INCLUDEDIR}/QXlsxL188-L194。3.4 find_package 后可用变量QXlsxQt5Config.cmake/QXlsxQt6Config.cmake会额外导出三个变量模板见 cmake/modules/qxlsx-config.cmake.inQXlsxQt5_INCLUDE_DIR或QXlsxQt6_INCLUDE_DIR头文件目录QXlsxQt5_LIBRARY_DIR库文件目录QXlsxQt5_LIBRARIES链接目标名值为QXlsxQt5。日常使用推荐直接链接QXlsx::QXlsx该 target 已包含正确的包含目录与链接依赖无需手动引用上述变量。四、方案三免安装使用add_subdirectory 与 FetchContent官方文档提供两种免安装方案适合不想向系统安装库的开发场景。4.1 方式一add_subdirectory 子目录把 QXlsx 源码放进你的工程目录或通过add_subdirectory指向外部路径然后在CMakeLists.txt中add_subdirectory(QXlsx) target_link_libraries(myapp PRIVATE QXlsx::QXlsx)仓库内的 HelloWorld/CMakeLists.txt 就是这一方式的完整范例它先探测 Qt 版本再add_subdirectory(QXlsx)L15最后把HelloWorld与QXlsx::QXlsx链接L21。注意该示例工程目录中已包含一份完整的 QXlsx 源码副本见 HelloWorld/QXlsx/CMakeLists.txt。当 QXlsx 不在当前子目录而位于其他位置时可显式指定源码目录与构建目录如 ExcelViewer/CMakeLists.txt#L16-L20add_subdirectory( ${CMAKE_CURRENT_SOURCE_DIR}/../QXlsx ${CMAKE_CURRENT_BINARY_DIR}/QXlsx_build )这种方式下 QXlsx 的QT_VERSION_MAJOR探测同样生效若你的工程与 QXlsx 的 Qt 需求不同需在add_subdirectory之前用set(QT_VERSION_MAJOR ...)统一版本避免出现 Qt 版本不一致导致的链接错误。4.2 方式二FetchContent 远程拉取FetchContent_Declare( QXlsx GIT_REPOSITORY https://github.com/QtExcel/QXlsx.git GIT_TAG sha-of-the-commit SOURCE_SUBDIR QXlsx ) FetchContent_MakeAvailable(QXlsx) target_link_libraries(myapp PRIVATE QXlsx::QXlsx)要点说明GIT_TAG建议使用具体提交的 SHA官方文档示例为sha-of-the-commit以保证构建可复现也可改用分支名或 tag但可复现性较弱SOURCE_SUBDIR QXlsx仓库根目录下 QXlsx 库源码所在的子目录必须保留该设置否则 CMake 无法定位 QXlsx 的顶层CMakeLists.txt在当前镜像环境下GIT_REPOSITORY可替换为你实际可达的仓库地址例如git clone https://gitcode.com/gh_mirrors/qx/QXlsx获取源码后使用本地路径或 add_subdirectory。4.3 两种免安装方式如何选择add_subdirectory源码已在本地、便于断点调试、可随手修改 QXlsx 源码适合深度定制或离线环境FetchContent自动获取指定版本、无需把第三方源码纳入你的版本库适合追求依赖声明化的工程但首次构建需要网络拉取。五、进阶配置静态库、共享库与编译选项QXlsx 的 CMake 通过option(BUILD_SHARED_LIBS Build in shared lib mode OFF)QXlsx/CMakeLists.txt#L50控制库类型默认 OFF 即静态库注释说明这是历史遗留的默认值。若需共享库cmake ../QXlsx/ -DBUILD_SHARED_LIBSON共享库构建时会额外导出QXlsx_SHAREDLIB编译宏L179-L181。此外 QXlsx 的库构建还施加了严格的 Qt 编译约束QT_NO_KEYWORDS、QT_NO_CAST_TO_ASCII等见 L149-L159保证库自身代码遵循 Qt 编码规范MSVC 下会追加/permissive以覆盖自动追加的/permissive-L162-L166非 Windows 平台则定义QT_STRICT_ITERATORSL169-L175。这些选项通常无需应用工程干预了解即可。六、常见问题与排错find_package找不到 QXlsxQt5/QXlsxQt6确认已执行cmake --install .且CMAKE_PREFIX_PATH包含-DCMAKE_INSTALL_PREFIX指定的目录例如cmake .. -DCMAKE_PREFIX_PATH/your/prefixQt 版本不符合预期QXlsx 默认按Qt6、Qt5顺序自动探测QXlsx/CMakeLists.txt#L17-L20若需强制 Qt 5在构建 QXlsx 与链接的应用工程两侧都统一设置QT_VERSION_MAJOR链接错误 / 头文件缺失检查是否直接使用QXlsx::QXlsx链接——该 target 已传播头文件路径与 Qt 依赖不要手动把header/加入include_directories绕过 target 机制版本兼容检查失败find_package请求的版本高于已安装版本时QXlsxQt5ConfigVersion.cmake会打印VERSION CHECK FAILED FOR QXlsxQt5. WANTED ..., HAVE 1.5.1此时应升级 QXlsx 或降低请求版本。七、补充qmake 方式与更多示例虽然本指南聚焦 CMake仓库同样提供 qmake 支持QXlsx/QXlsx.pro 与 QXlsx/QXlsx.pri通过include(QXlsx.pri)集成且同样区分 Qt 5C11与 Qt 6C17并支持QT_VERSION_MAJOR探测逻辑见 QXlsx/QXlsx.pri#L10-L18。仓库内可直接参考的 CMake 示例工程包括HelloWorld/CMakeLists.txtadd_subdirectory 最小范例ExcelViewer/CMakeLists.txt指定 Qt 6、外部路径 add_subdirectory 与 Git 哈希注入范例DateTime/CMakeLists.txt早期手工收集源码文件的样板式写法可作为理解 CMake target 封装必要性的对比。建议新工程一律采用文档所述的QXlsx::QXlsxtarget 链接方式既有官方支持又便于后续升级。赞分享数据分析【免费下载链接】QXlsxExcel file(*.xlsx) reader/writer library using Qt. Descendant of QtXlsxWriter.项目地址https://gitcode.com/gh_mirrors/qx/QXlsx点击查看免费下载相关推荐FTXUI 的 CMake 集成指南FetchContent、find_package 与 Submodule 三种接入方式及构建选项详解FTXUI 的 CMake 集成指南FetchContent、find_package 与 Submodule 三种接入方式及构建选项详解 FTXUICUI组件Open3D 集成指南通过 CMake find_package 使用预安装的 Open3D 包open3d-cmake-find-package 实战Open3D 集成指南通过 CMake find_package 使用预安装的 Open3D 包open3d cmake find package 实战计算机视觉图形学3D渲染科学计算curl 与 libcurl 的 CMake 构建指南从配置、安装到 find_package 集成curl 与 libcurl 的 CMake 构建指南从配置、安装到 find_package 集成 本文基于 curl 仓库官方文档 docs/INSTALCLI网络通信上一篇transcribe.cpp 模型家族速查清单16 语音识别模型的架构、语言、延迟一图流下一篇Diffusers 实战用 InstructPix2Pix 微调 Stable Diffusion 实现指令驱动图像编辑创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

相关新闻

OpenBidKit 标书智能体文本模型配置完全指南：从服务商选择到并发调优

OpenBidKit 标书智能体文本模型配置完全指南：从服务商选择到并发调优

AI 应用AI 写作人工智能AI Agent企业应用 【免费下载链接】OpenBidKit_Yibiao 开箱即用的AI标书编写工具，标书AI生成工具，投标工具箱、知识库、标书查重、废标项检查，完全开源免费，欢迎使用 项目地址： https://gitcode…

2026/10/5 2:22:35 阅读更多 →
JSON 数据交换格式完整语法指南——Learn X in Y Minutes 捷克语教程解析

JSON 数据交换格式完整语法指南——Learn X in Y Minutes 捷克语教程解析

文档教程 【免费下载链接】learnxinyminutes-docs Code documentation written as code! How novel and totally my idea! 项目地址： https://gitcode.com/gh_mirrors/le/learnxinyminutes-docs 点击查看 免费下载 JSON（JavaScript Object Notation&…

2026/10/5 2:22:35 阅读更多 →
TIL：用 GitHub Actions 标签机制阻止未就绪的 PR 被合并

TIL：用 GitHub Actions 标签机制阻止未就绪的 PR 被合并

文档教程知识库 【免费下载链接】til :memo: Today I Learned 项目地址： https://gitcode.com/gh_mirrors/ti/til 点击查看 免费下载 本指南讲解如何基于 GitHub Actions 原生能力，为 PR 上的 no merge、wip 等标签自动生成一个失败的检查（f…

2026/10/5 2:22:35 阅读更多 →

最新新闻

AURIX TC3XX旋变软解码为何必须用EDSADC？

AURIX TC3XX旋变软解码为何必须用EDSADC？

1. 这不是“调个ADC”那么简单：为什么旋变软解码在AURIX TC3XX上必须用EDSADC你搜“AURIX 旋变解码”，十有八九会看到一堆人卡在“怎么让旋变信号真正跑起来”。不是ADC读不到电压，是读到了也解不出角度——或者解出来抖得像手机没信号。我去…

2026/10/6 5:52:09 阅读更多 →
Godot编辑器移植鸿蒙PC：难度拆解与可行路线解析

Godot编辑器移植鸿蒙PC：难度拆解与可行路线解析

后台经常有人拿“把 Godot 游戏编辑器移植到鸿蒙 PC”这个问题来问我，但这个说法其实省略了最关键的限定条件。你是想让鸿蒙 PC 设备能跑 Godot 做的游戏，还是想让 Godot 编辑器本身在这个系统上打开、正常运行，甚至是用它导出鸿蒙应用包&…

2026/10/6 5:52:09 阅读更多 →
74LS161与74HC390在Multisim中实现六进制和六十进制计数器

74LS161与74HC390在Multisim中实现六进制和六十进制计数器

1. 为什么还要折腾74系列计数器数字电路实验里，计数器是最基础也最容易翻车的模块之一。74LS161和74HC390这两颗芯片，一颗是四位二进制同步计数器，一颗是双十进制计数器，几乎覆盖了从模2到模100的所有计数需求。但很多人在Multisi…

2026/10/6 5:52:09 阅读更多 →
OmniGame：基于WebRTC与P2P的无服务器网页游戏运行时

OmniGame：基于WebRTC与P2P的无服务器网页游戏运行时

1. 项目概述：当网页小游戏不再需要“服务器”这个中间人你有没有试过点开一个网页小游戏，等三秒加载、再等两秒初始化、最后卡在“正在连接游戏服务器…”？我做过六年网页游戏前端架构，也带团队从零搭过三款上线超千万用户的H5小游…

2026/10/6 5:52:09 阅读更多 →
从零到15%引用率：AI搜索代码级GEO优化指南

从零到15%引用率：AI搜索代码级GEO优化指南

这两年做网站的站长，应该都有一个明显感受：传统搜索流量在下滑，AI 搜索带来的推荐流量在涨。但很多人发现，自己的内容明明写得很认真，搜索结果页排名也不错，偏偏在 AI 搜索里不被引用，甚至一次都…

2026/10/6 5:52:09 阅读更多 →
电子维修必修课：丝印识别的解码逻辑与实战避坑指南

电子维修必修课：丝印识别的解码逻辑与实战避坑指南

1. 为什么丝印是电子维修人最该练熟的“第一眼功夫”你拆开一台故障电源板，手边没图纸、没BOM、连厂家都倒闭十年了——这时候，能让你在30秒内判断出那个黑黢黢小元件到底是1N4007还是SS34的，不是万用表，不是示波器，而…

2026/10/6 5:51:08 阅读更多 →

日新闻

杰理AC7916A硬件设计全指南：电源、时钟与射频三大关键

杰理AC7916A硬件设计全指南：电源、时钟与射频三大关键

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 1:01:12 阅读更多 →
探针座选型指南：从需求梳理到验收避坑，稳稳解决半导体测试难题

探针座选型指南：从需求梳理到验收避坑，稳稳解决半导体测试难题

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 1:01:36 阅读更多 →
SO-DIMM内存设计指南：DDR3与DDR4引脚、拓扑、布线及调试

SO-DIMM内存设计指南：DDR3与DDR4引脚、拓扑、布线及调试

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 1:01:44 阅读更多 →

周新闻

KT148A语音芯片外挂8002D功放的工程实践指南

KT148A语音芯片外挂8002D功放的工程实践指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/5 5:06:42 阅读更多 →
LLC谐振变换器增益公式推导：从FHA等效到完整归一化表达式

LLC谐振变换器增益公式推导：从FHA等效到完整归一化表达式

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 5:29:09 阅读更多 →
ARM架构深度解析：从RISC设计理念到交叉编译实战

ARM架构深度解析：从RISC设计理念到交叉编译实战

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/5 3:06:17 阅读更多 →

月新闻

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/4 11:40:45 阅读更多 →
Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 4:21:51 阅读更多 →
黑夜航拍船只数据集训练YOLOV5模型全流程解析

黑夜航拍船只数据集训练YOLOV5模型全流程解析

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/10/6 1:18:13 阅读更多 →