nlohmann/json

项目介绍

nlohmann/json 是一个单头文件 C++ 库，目标是让 JSON 像 C++ 的一等数据类型一样使用。你可以直接写 json j;，用 [] 逐层赋值，再用 << 输出，而不必先构造一个独立的解析器对象。设计目标是在 C++ 中还原 Python 等语言里 JSON 的直观写法，并利用现代 C++ 的运算符特性实现 (设计目标)。

库以 RFC 8259 为目标，功能不止解析：提供类似 STL 容器的访问方式、与标准容器及自定义类型的互转、JSON Pointer（RFC 6901）、JSON Patch（RFC 6902）、JSON Merge Patch（RFC 7396），以及 BSON、CBOR、MessagePack、UBJSON、BJData、BON8 等二进制编码 (二进制格式)。适合希望用更顺手 API 处理 JSON 的 C++ 项目，而不是只追求极简 C 风格解析的场景。

快速使用

项目是 header-only 的：引入 single_include/nlohmann/json.hpp 或下载发布包，然后加上 include 和 using nlohmann::json 即可 (集成方式)。读取文件的最小示例：

#include <fstream>
#include <nlohmann/json.hpp>
using nlohmann::json;

int main() {
    std::ifstream f("example.json");
    json data = json::parse(f);
    return 0;
}

CMake 项目可以定位包并链接接口目标：

find_package(nlohmann_json 3.12.0 REQUIRED)
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

构建并运行测试：mkdir build && cd build && cmake .. -DJSON_BuildTests=On && cmake --build . && ctest --output-on-failure。测试阶段会从外部仓库下载 JSON 测试数据，离线环境需要额外配置 (执行单元测试)。

使用约束

• 要求 C++11 或更高版本。项目列出的已测试编译器覆盖 GCC 4.8、Clang 3.4 到较新的 MSVC、Intel 和 CUDA 编译器；其他版本可能可用，但不在保证范围内 (支持的编译器)。
• 默认按 UTF-8 处理输入；std::u16string 和 std::u32string 可按 UTF-16/UTF-32 解析，但仅限内存输入，从文件或其他输入容器读取时不支持。Latin-1、ISO 8859-1 等编码不受支持。
• 默认把注释和尾随逗号视为错误。parse 提供 ignore_trailing_commas 选项，注释仍需显式设置才能忽略 (注释)。
• 默认不保留对象键的插入顺序；需要顺序时可用 nlohmann::ordered_json (对象键顺序)。
• 维护者不建议从 json 隐式转换到 C++ 类型；可通过 JSON_USE_IMPLICIT_CONVERSIONS=0 或 CMake 选项 JSON_ImplicitConversions=OFF 关闭。
• 许可证为 MIT (许可证)。

HotRepo 点评

在 2026-11-06 的 C++ 日榜记录中，项目当天最好名次为第 5，新增 8 星；仓库总量约 5.08 万星、7518 个 fork。Hacker News 上的讨论呈现分歧：有用户认可其 API 的易用性，但担心编译时间，因而在部分场景选择 rapidjson (评论)；也有用户报告在 ESP32 单核模式下使用，性能足够 (回复)。取舍点很明确：API 顺手、功能齐全，但编译开销和解析吞吐不如专用解析器。2019 年的讨论还提到，在头文件中使用 json_fwd.hpp 可以限制编译时间成本 (评论)。