VS Studio中nlohmann JSON解析中文乱码问题

Question

在使用 Visual Studio 开发 C++ 项目时，集成 nlohmann/json 库解析包含中文的 JSON 字符串常出现乱码问题。典型表现为：读取含中文字段的 JSON 文件或字符串后，输出显示为问号、方块或乱码字符。该问题多源于源文件编码格式（如 GBK）与程序运行时 UTF-8 编码不一致，或未正确设置控制台输出编码。尽管 nlohmann/json 原生支持 UTF-8，但 Windows 平台默认代码页非 UTF-8，导致宽字符转换失败。如何确保源文件、字符串编码与运行环境统一，是解决中文乱码的关键所在。

Answer 1

1. 问题现象与初步诊断

在使用 Visual Studio 开发 C++ 项目并集成 nlohmann/json 库时，开发者常遇到解析包含中文的 JSON 字符串后输出乱码的问题。典型表现为控制台显示为“？？”、“□”或不可读字符。该现象多出现在 Windows 平台下，尤其当源文件以 GBK 或 ANSI 编码保存时。

尽管 nlohmann/json 原生支持 UTF-8 编码，但由于 Visual Studio 默认使用系统本地代码页（如简体中文 Windows 使用 CP936/GBK），导致字符串在编译期即被错误解码。此外，控制台默认代码页通常为 437 或 936，而非 UTF-8，进一步加剧了输出乱码问题。

2. 深层原因分析：编码链断裂

• 源文件编码不一致：Visual Studio 中若未明确设置文件为 UTF-8（带 BOM 或无 BOM），则可能以 ANSI/GBK 存储，导致编译器误读中文字符。
• 运行时环境编码缺失：Windows 控制台默认不启用 UTF-8 模式（chcp 65001），宽字符转换失败。
• JSON 解析器输入非 UTF-8：即使库支持 UTF-8，若传入的字符串实际为 GBK 编码，则解析结果自然出错。
• 标准输出流未适配 Unicode：C++ 的 std::cout 在非 UTF-8 环境下无法正确渲染多字节字符。

3. 编码一致性检查流程图

graph TD
    A[JSON 源文件] -->|编码格式| B{是否 UTF-8?}
    B -- 否 --> C[转换为 UTF-8]
    B -- 是 --> D[读取为 std::string]
    D --> E[nlohmann::json::parse()]
    E --> F{解析成功?}
    F -- 否 --> G[检查输入是否含 BOM 或非法字节]
    F -- 是 --> H[输出到控制台]
    H --> I{控制台代码页=65001?}
    I -- 否 --> J[执行 chcp 65001 或 SetConsoleOutputCP(65001)]
    I -- 是 --> K[正常显示中文]

4. 解决方案层级结构

层级	措施	适用场景	实施难度
Level 1	保存源文件为 UTF-8 with BOM	小型项目、快速修复	★☆☆☆☆
Level 2	使用 #pragma execution_character_set("utf-8")	Visual Studio 特定项目	★★☆☆☆
Level 3	调用 SetConsoleOutputCP(65001)	控制台程序输出	★★★☆☆
Level 4	预处理 GBK 转 UTF-8（Windows API MultiByteToWideChar）	遗留系统兼容	★★★★☆
Level 5	CMake 配置统一编码策略 + ICU 库支持	跨平台大型项目	★★★★★

5. 实际代码示例：完整解决方案

#include <iostream>
#include <fstream>
#include <string>
#include <windows.h>
#define JSON_USE_IMPLICIT_CONVERSIONS 1
#include <nlohmann/json.hpp>

// 设置控制台为 UTF-8 输出
void SetupConsoleUTF8() {
    SetConsoleOutputCP(CP_UTF8);
    SetConsoleCP(CP_UTF8);
}

// GBK to UTF-8 转换函数（适用于读取 GBK 编码 JSON 文件）
std::string GBKToUTF8(const std::string& gbkStr) {
    int wideLen = MultiByteToWideChar(CP_ACP, 0, gbkStr.c_str(), -1, nullptr, 0);
    wchar_t* wideBuf = new wchar_t[wideLen];
    MultiByteToWideChar(CP_ACP, 0, gbkStr.c_str(), -1, wideBuf, wideLen);

    int utf8Len = WideCharToMultiByte(CP_UTF8, 0, wideBuf, -1, nullptr, 0, nullptr, nullptr);
    char* utf8Buf = new char[utf8Len];
    WideCharToMultiByte(CP_UTF8, 0, wideBuf, -1, utf8Buf, utf8Len, nullptr, nullptr);

    std::string result(utf8Buf);
    delete[] wideBuf;
    delete[] utf8Buf;
    return result;
}

int main() {
    SetupConsoleUTF8();

    // 方法一：直接使用 UTF-8 编码的字符串（确保源文件保存为 UTF-8）
    std::string jsonStr = R"({"name": "张三", "city": "北京"})";
    
    try {
        auto j = nlohmann::json::parse(jsonStr);
        std::cout << std::setw(4) << j << std::endl;  // 正常输出中文
    } catch (const nlohmann::json::exception& e) {
        std::cerr << "Parse error: " << e.what() << std::endl;
    }

    // 方法二：读取外部 GBK 编码文件并转换
    std::ifstream file("data.json");  // 假设文件为 GBK 编码
    if (file.is_open()) {
        std::string content((std::istreambuf_iterator<char>(file)),
                            std::istreambuf_iterator<char>());
        file.close();

        std::string utf8Content = GBKToUTF8(content);
        auto j = nlohmann::json::parse(utf8Content);
        std::cout << std::setw(4) << j << std::endl;
    }
}