1. 为什么还要折腾 QJson 的编译QJson 这个库做 Qt 桌面开发的人多少都听过。它是一个基于 Qt 的轻量级 JSON 解析库能把 JSON 文本直接映射成 QVariant 对象也能把 QVariant 反向序列化成 JSON 字符串。相比 Qt 自带的 QJsonDocument它的 API 更贴近“随手用”的直觉尤其在处理嵌套结构、数组和类型转换时代码量能少一大截。但问题也恰恰出在这里。QJson 并不是 Qt 官方模块它最早是一个独立开源项目后来虽然被不少项目引用但版本迭代慢、构建脚本老旧加上 Qt 自身从 qmake 到 CMake 的迁移导致很多人在编译阶段就卡住了。我见过太多人拿到源码后第一步qmake就报错或者编译通过但链接时找不到符号又或者在自己的工程里引入后出现诡异的运行时崩溃。这篇内容就是把我自己反复编译 QJson 踩过的坑、试过的方案、最终稳定的流程完整梳理出来。适合两类人看一类是第一次接触 QJson、想把它集成到自己 Qt 工程里的开发者另一类是被编译错误折磨过、想找一份“能直接抄”的构建配置的人。全文基于 Qt 5 和 Qt 6 的常见环境展开Qt 4 的情况会单独提一句但不会作为重点。需要提前说明的是QJson 的源码版本差异比较大不同分支的构建文件可能完全不同。我下面讲的是目前社区里流传较广、相对稳定的一个版本结构如果你手里的源码目录和我描述的不一样先别急着照搬看完第二节的目录分析再动手。2. 编译前的环境确认与源码结构分析2.1 确认 Qt 版本和编译器组合QJson 的编译成败很大程度上取决于你的 Qt 版本和编译器是否匹配。我实测下来以下几种组合是比较稳的Qt 版本编译器构建方式稳定性Qt 5.12 LTSMSVC 2017/2019qmake nmake很稳Qt 5.15 LTSMSVC 2019qmake nmake很稳Qt 5.15 LTSMinGW 8.1qmake mingw32-make稳Qt 6.2 LTSMSVC 2019CMake Ninja较稳Qt 6.5 LTSMSVC 2022CMake Ninja较稳Qt 5.9MinGW 5.3qmake mingw32-make一般这里有个关键点Qt 6 默认不再提供 qmake 的完整支持虽然 qmake 还能用但 QJson 老版本的 .pro 文件在 Qt 6 下经常出现模块找不到的问题。所以如果你用的是 Qt 6我建议直接走 CMake 路线或者手动补一个 CMakeLists.txt。另一个坑是32 位和 64 位的混用。QJson 编译出来的库必须和你的主工程位数一致否则链接阶段会报“模块计算机类型 x64 与目标计算机类型 x86 冲突”。这个错误看起来很吓人其实就是位数不匹配重新用对应版本的 Qt 命令行工具编译一遍就行。2.2 源码目录里哪些文件真正有用拿到 QJson 源码后先别急着打开 .pro 文件。我建议你先花两分钟看清楚目录结构因为不同来源的压缩包里垃圾文件和有效文件混在一起的情况很常见。一个典型的 QJson 源码目录大概长这样qjson/ ├── src/ │ ├── json_parser.cpp │ ├── json_parser.h │ ├── json_scanner.cpp │ ├── json_scanner.h │ ├── parser.cpp │ ├── parser.h │ ├── qjson_export.h │ ├── qjson_global.h │ ├── qjsonobject.cpp │ ├── qjsonobject.h │ ├── qjsonvalue.cpp │ ├── qjsonvalue.h │ └── qjson.pro ├── tests/ ├── examples/ ├── README.md └── qjson.pro真正需要编译进库的就是src/下面那些 .cpp 和 .h。tests/和examples/可以暂时不管它们依赖额外的测试框架第一次编译时建议直接跳过减少变量。注意有些版本的 QJson 源码里src/下面还有一个qjson_export.h这个文件是自动生成的但有些压缩包里给的是空文件或者占位文件。如果编译时报“未定义 QJSON_EXPORT”就是这个头文件的问题需要手动补上导出宏定义。2.3 清理掉可能干扰编译的旧文件这一步很多人会忽略但实际非常关键。如果你之前尝试编译过 QJson目录里可能残留了Makefile、.qmake.stash、debug/、release/、build/这些中间产物。不同版本的 qmake 生成的 Makefile 格式不一样混在一起会导致莫名其妙的错误。我的习惯是在开始编译前先在源码根目录执行一次清理# 如果你在 Windows 的 Qt 命令行里 del Makefile del .qmake.stash rmdir /s /q debug rmdir /s /q release rmdir /s /q build# 如果你在 Linux 或 macOS 的终端里 rm -f Makefile .qmake.stash rm -rf debug release build清理完之后再确认一下src/qjson.pro里的TARGET和DESTDIR配置。有些版本默认把库输出到系统目录这在没有管理员权限的机器上会直接失败。我一般会改成输出到源码目录下的lib/文件夹方便后续引用。3. 用 qmake 编译 QJson 的完整流程3.1 打开正确的命令行环境Windows 下编译 Qt 项目最容易出错的地方就是命令行环境不对。你不能直接开一个普通的 cmd 或者 PowerShell那样找不到 qmake、nmake、mingw32-make 这些工具。正确的做法是从开始菜单里找到对应 Qt 版本的命令行工具。比如你用 Qt 5.15.2 的 MSVC 2019 64 位版本就打开 “Qt 5.15.2 (MSVC 2019 64-bit)” 那个快捷方式。打开之后命令行提示符前面通常会带一个环境标识这时候再输入qmake -v应该能看到正确的 Qt 版本和路径。如果你用的是 MinGW 版本就打开 “Qt 5.15.2 (MinGW 8.1 64-bit)” 那个。输入qmake -v和mingw32-make -v都应该能正常输出版本信息。实操心得我习惯在打开命令行后先执行一次where qmakeWindows或which qmakeLinux/macOS确认当前环境调用的 qmake 就是我想要的那个版本。因为很多人的机器上装了多个 Qt 版本环境变量一乱调用的就是另一个版本的 qmake编译出来的库自然和主工程不匹配。3.2 生成 Makefile 并检查关键配置进入 QJson 源码的src/目录执行qmake qjson.pro如果一切正常你会看到目录下多了一个Makefile。这时候别急着 make先打开 Makefile 扫一眼几个关键变量CC和CXX确认编译器路径是你期望的那个。INCPATH确认包含了 Qt 的头文件路径。LIBS确认链接了 QtCore 和 QtGui有些版本需要 QtGui有些只需要 QtCore。DESTDIR确认库的输出目录。我遇到过一种情况qmake 执行成功但 Makefile 里的INCPATH指向了一个不存在的 Qt 头文件目录原因是 Qt 安装时某些模块没勾选。这种问题在 make 阶段才会暴露提前看一眼能省不少时间。3.3 执行编译并处理常见报错生成 Makefile 后执行编译命令# MSVC 环境 nmake # MinGW 环境 mingw32-make # Linux/macOS 环境 make如果源码本身没问题环境也匹配这一步应该能顺利跑完最终在DESTDIR指定的目录下生成qjson.dll和qjson.libWindows或libqjson.so/libqjson.dylibLinux/macOS。但现实往往没那么顺利。下面是我遇到过的几个典型报错和对应的处理方式报错一fatal error C1083: 无法打开包括文件: qjson_export.h这个错误说明编译器找不到qjson_export.h。先确认这个文件是否存在于src/目录下。如果不存在需要手动创建一个内容大致如下#ifndef QJSON_EXPORT_H #define QJSON_EXPORT_H #include QtCore/qglobal.h #if defined(QJSON_LIBRARY) # define QJSON_EXPORT Q_DECL_EXPORT #else # define QJSON_EXPORT Q_DECL_IMPORT #endif #endif // QJSON_EXPORT_H然后在qjson.pro里确认有DEFINES QJSON_LIBRARY这一行。这个宏的作用是告诉编译器“我现在是在编译库本身不是在引用库”从而正确导出符号。报错二undefined reference to QJson::Parser::parse这是链接错误通常发生在你试图把 QJson 静态库链接到自己的工程时。原因可能是库文件没有正确生成或者链接顺序不对。先确认lib/目录下确实有qjson.lib或libqjson.a然后在自己的 .pro 文件里检查LIBS的写法。报错三error: QVariant::Type has not been declared这个错误在 Qt 6 下比较常见因为 Qt 6 把QVariant::Type改成了QMetaType::Type。如果你用的是 Qt 6需要手动修改源码里涉及QVariant::Type的地方替换成QMetaType::Type。这也是为什么我前面说 Qt 6 下建议走 CMake 路线因为老版本的 qmake 工程文件在 Qt 6 下需要改的地方比较多。3.4 验证编译产物是否可用编译完成后不要直接扔到主工程里用。先做一个最小验证新建一个空的 Qt Console 工程把 QJson 的头文件目录和库文件目录配置进去写几行代码测试解析和序列化。#include QCoreApplication #include QDebug #include parser.h #include qjsonobject.h int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); QJson::Parser parser; bool ok; QVariant result parser.parse({\name\:\test\,\value\:123}, ok); if (ok) { QJson::QObjectHelper::qvariant2qobject(result.toMap(), nullptr); qDebug() Parse success: result; } else { qDebug() Parse failed at line parser.errorLine(); } return a.exec(); }如果这段代码能编译、链接、运行并且输出正确的解析结果说明库本身没问题。如果链接时报错大概率是库的位数不对或者头文件和库文件的版本不匹配。4. Qt 6 下用 CMake 编译 QJson 的替代方案4.1 为什么 Qt 6 下 qmake 路线越来越难走Qt 6 对构建系统做了一次大调整CMake 成了官方推荐的首选qmake 虽然还在但很多新特性和模块配置在 qmake 下已经不再更新。QJson 作为一个老项目它的 .pro 文件是基于 Qt 4/5 时代的写法在 Qt 6 下会遇到几个硬性问题QT gui在 Qt 6 下需要改成QT core gui而且某些 Qt 6 版本对 gui 模块的依赖更严格。CONFIG staticlib在 Qt 6 下的行为和 Qt 5 不完全一致静态库的导出宏需要额外处理。QMAKE_CXXFLAGS里的一些老参数在 Qt 6 的编译器下会报 warning 甚至 error。与其花时间改 .pro 文件不如直接写一个 CMakeLists.txt把 QJson 的源码当成自己工程的一部分来编译。这样不仅 Qt 6 下能用Qt 5 下也能用而且跨平台一致性更好。4.2 手写一个可复用的 CMakeLists.txt下面这个 CMakeLists.txt 是我在实际项目中反复用过的支持 Qt 5 和 Qt 6支持静态库和动态库切换输出目录也做了统一处理cmake_minimum_required(VERSION 3.16) project(QJson LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core) find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core) set(QJSON_SOURCES src/json_parser.cpp src/json_scanner.cpp src/parser.cpp src/qjsonobject.cpp src/qjsonvalue.cpp ) set(QJSON_HEADERS src/json_parser.h src/json_scanner.h src/parser.h src/qjson_export.h src/qjson_global.h src/qjsonobject.h src/qjsonvalue.h ) add_library(QJson STATIC ${QJSON_SOURCES} ${QJSON_HEADERS}) target_include_directories(QJson PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src $INSTALL_INTERFACE:include/QJson ) target_link_libraries(QJson PUBLIC Qt${QT_VERSION_MAJOR}::Core) target_compile_definitions(QJson PRIVATE QJSON_LIBRARY) set_target_properties(QJson PROPERTIES OUTPUT_NAME qjson ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin )把这个文件放在 QJson 源码根目录然后执行cmake -B build -DCMAKE_PREFIX_PATH/path/to/Qt/6.x.x/gcc_64 cmake --build build --config Release编译完成后build/lib/下会生成libqjson.a头文件在src/下直接在自己的 CMake 工程里add_subdirectory或者find_package都能用。4.3 把 QJson 集成到自己工程里的两种方式第一种是源码内嵌把 QJson 的src/目录整个拷到自己工程的third_party/qjson/下然后在顶层 CMakeLists.txt 里add_subdirectory(third_party/qjson)最后在目标链接时加上target_link_libraries(你的目标 PRIVATE QJson)。这种方式最省心版本可控调试也方便。第二种是预编译库引用先把 QJson 单独编译成静态库或动态库然后在自己的工程里通过find_library或直接指定路径来链接。这种方式适合多个工程共用同一个 QJson 库的场景但要注意头文件版本和库版本必须一致否则会出现“编译通过但运行崩溃”的问题。注意如果你用的是动态库方式部署时需要把qjson.dll或libqjson.so一起打包到可执行文件目录下否则运行时会报“找不到 qjson.dll”。静态库方式则没有这个问题但会让最终可执行文件体积变大。5. 编译过程中最容易踩的五个坑5.1 坑一头文件里的导出宏没定义这是最经典的一个坑。QJson 的头文件里大量使用了QJSON_EXPORT宏如果这个宏没有正确定义编译阶段可能只是警告但链接阶段一定会报“无法解析的外部符号”。正确的做法是在编译库本身时定义QJSON_LIBRARY在引用库时不要定义这个宏。这样QJSON_EXPORT会自动切换成Q_DECL_EXPORT或Q_DECL_IMPORT。如果你用的是 CMake就像我上面写的那样用target_compile_definitions(QJson PRIVATE QJSON_LIBRARY)来保证只有编译库时才定义这个宏。5.2 坑二Qt 模块依赖漏掉了QJson 的核心依赖是 QtCore但有些版本的源码里还用到了 QtGui 里的东西比如QColor的序列化。如果你只链接了 QtCore编译时可能不报错但链接时会找不到QColor相关的符号。我的建议是第一次编译时先把QT core gui都加上等编译通过后再根据实际使用情况精简。多链接一个 QtGui 模块对最终体积的影响远小于反复排查链接错误的时间成本。5.3 坑三字符编码导致的编译失败QJson 的源码里有一些字符串字面量在 MSVC 下如果源文件编码和编译器默认编码不一致会报C4819警告严重时直接报错。解决办法是在 .pro 文件里加上QMAKE_CXXFLAGS /utf-8或者在 CMake 里加上if(MSVC) target_compile_options(QJson PRIVATE /utf-8) endif()这个坑在中文 Windows 环境下特别常见因为系统默认代码页是 GBK而源码文件可能是 UTF-8 无 BOM 格式。5.4 坑四静态库和动态库的宏冲突如果你先编译了动态库又编译了静态库两个版本的qjson.lib混在一起链接时会出现“符号重复定义”的错误。解决办法是每次切换库类型时先彻底清理构建目录再重新生成。我自己的习惯是静态库和动态库分别放在不同的构建目录下比如build-static/和build-shared/互不干扰。5.5 坑五Qt 版本升级后没有重新编译Qt 从 5.15 升级到 6.2或者从 6.2 升级到 6.5ABI 是有变化的。如果你用 Qt 5.15 编译的 QJson 库直接拿到 Qt 6.5 的工程里链接即使编译通过运行时也可能崩溃。正确的做法是每次 Qt 版本变更后QJson 库都要重新编译一遍。不要试图跨大版本复用二进制库。6. 常见问题速查与排查思路6.1 编译阶段问题速查表现象可能原因排查方式解决方式qmake 找不到命令行环境不对where qmake打开对应 Qt 版本的命令行工具找不到 qjson_export.h文件缺失或路径不对检查 src 目录手动创建导出宏头文件C1083 无法打开包括文件Qt 头文件路径不对检查 Makefile 的 INCPATH确认 Qt 安装完整C4819 编码警告源码编码与编译器不一致查看源文件编码加 /utf-8 编译选项LNK2019 无法解析的外部符号导出宏未定义或库未链接检查 QJSON_LIBRARY 宏正确配置编译定义LNK1112 模块计算机类型冲突32 位和 64 位混用检查 Qt 版本和编译器统一使用相同位数6.2 链接阶段问题速查表现象可能原因排查方式解决方式找不到 qjson.lib库输出目录不对检查 DESTDIR修改输出目录或添加库搜索路径符号重复定义静态库和动态库混用检查链接的库文件清理后只保留一种库运行时崩溃Qt 版本不匹配检查编译和运行的 Qt 版本重新编译 QJson找不到 qjson.dll动态库未部署检查可执行文件目录拷贝 dll 到输出目录解析结果为空JSON 格式错误检查 errorLine 和 errorString修正 JSON 输入6.3 我个人的排查习惯遇到编译问题时我一般按这个顺序排查先看第一条错误。编译器报错往往是一连串的但第一条才是根因后面的都是连锁反应。确认环境变量。qmake -v、where nmake、where cl这三个命令的输出能解决大部分环境问题。清理后重试。删掉所有中间文件重新 qmake 和 make能排除掉很多“上次编译残留”导致的问题。最小化复现。新建一个空工程只引入 QJson写最少的代码确认库本身没问题再排查自己工程的配置。对比官方示例。如果 QJson 源码里有 examples 目录先编译官方示例确认示例能跑通再改自己的代码。实操心得我习惯在编译 QJson 之前先在一个干净的虚拟机或者容器里跑一遍完整流程。这样能排除掉本机环境的各种干扰确认哪些步骤是真正必需的哪些只是我本机特有的配置。虽然多花十分钟但能省下后面几个小时甚至几天的排查时间。7. 编译完成后的集成与使用建议7.1 在自己的 qmake 工程里引用 QJson如果你用的是 qmake 工程引用 QJson 静态库的写法大致如下INCLUDEPATH $$PWD/third_party/qjson/src LIBS -L$$PWD/third_party/qjson/lib -lqjson # 如果是 Windows 下 MSVC 编译的动态库 LIBS -L$$PWD/third_party/qjson/lib -lqjson注意-lqjson在 Windows 下会去找qjson.lib在 Linux 下会去找libqjson.so或libqjson.a。路径里的$$PWD是 .pro 文件所在目录用相对路径能保证工程在不同机器上都能找到库文件。7.2 在自己的 CMake 工程里引用 QJson如果你用的是 CMake 工程并且已经把 QJson 作为子目录引入引用方式就很简单add_subdirectory(third_party/qjson) target_link_libraries(你的目标 PRIVATE QJson)如果 QJson 是预编译好的可以用find_libraryfind_library(QJSON_LIBRARY NAMES qjson PATHS ${CMAKE_SOURCE_DIR}/third_party/qjson/lib) find_path(QJSON_INCLUDE_DIR NAMES parser.h PATHS ${CMAKE_SOURCE_DIR}/third_party/qjson/src) target_include_directories(你的目标 PRIVATE ${QJSON_INCLUDE_DIR}) target_link_libraries(你的目标 PRIVATE ${QJSON_LIBRARY})7.3 使用 QJson 时的几个编码习惯QJson 的 API 设计比较灵活但灵活也意味着容易写出有隐患的代码。我自己的几个习惯是解析时始终检查ok标志不要假设输入一定是合法 JSON。序列化时注意QVariant的类型QVariantMap和QVariantList能正确序列化但自定义类型需要先转换成基础类型。处理大 JSON 时QJson 的解析器是递归下降的嵌套层级太深可能导致栈溢出实际项目中建议对输入做深度限制。如果 JSON 里包含中文确保解析和序列化时使用 UTF-8 编码避免出现乱码。8. 最后再分享几个实用技巧第一个技巧是关于编译缓存的。如果你需要反复编译 QJson 来测试不同配置建议用ccacheLinux/macOS或者clcacheWindows来加速。QJson 的源码量不大但反复清理重建还是很烦人的有了缓存能省不少时间。第二个技巧是关于版本管理的。QJson 的源码建议直接放进自己项目的版本控制里而不是依赖外部下载。因为 QJson 的官方仓库更新很慢有些版本甚至已经不再维护把源码固定在自己项目里能保证任何时候都能编译出可用的库。第三个技巧是关于跨平台构建的。如果你需要在 Windows、Linux、macOS 三个平台上都编译 QJson建议统一用 CMake并且把平台相关的编译选项用if(WIN32)、if(APPLE)、if(UNIX)分开处理。这样一份 CMakeLists.txt 就能覆盖三个平台比维护三套 .pro 文件省事得多。第四个技巧是关于调试符号的。Release 模式下编译的 QJson 库默认不带调试符号如果运行时崩溃堆栈信息会很难看。建议在开发阶段用 RelWithDebInfo 模式编译既有优化又有调试信息排查问题方便很多。set(CMAKE_BUILD_TYPE RelWithDebInfo)或者用 qmake 的话CONFIG force_debug_info QMAKE_CXXFLAGS_RELEASE /Zi QMAKE_LFLAGS_RELEASE /DEBUG这几个技巧都是我在实际项目中反复验证过的尤其是跨平台构建和调试符号这两点能帮你省下大量排查时间。QJson 本身不复杂复杂的是构建环境和版本匹配把这两件事理顺了后面用起来就很顺手了。