QT中JSON传输中文时出现乱码，如何正确设置编码？

Question

在Qt中通过QJsonDocument序列化中文字符串时出现乱码，根本原因常是JSON文本未以UTF-8编码保存或传输。Qt 5.0+ 默认使用UTF-8处理QString，但若手动将QJsonDocument.toJson()结果写入文件/网络流时未显式指定UTF-8编码（如 QFile未调用setCodec("UTF-8")，或QTextStream未设置.setCodec("UTF-8")），或HTTP响应头缺失Content-Type: application/json; charset=utf-8，均会导致接收端误判编码。此外，若原始QString含非UTF-8来源数据（如从GBK文件读取未转换），也会污染JSON。解决方案：①确保所有文本I/O统一使用UTF-8（QFile + QTextStream设UTF-8）；②网络传输时设置正确的HTTP头；③避免混用QTextCodec::setCodecForLocale()（已废弃）；④优先使用QJsonDocument::toJson(QJsonDocument::Compact)并直接操作字节数组（QByteArray），因其原生为UTF-8。验证方法：打印toUtf8().toHex()确认BOM未出现且中文为合法UTF-8字节序列。

Answer 1

```html

一、现象层：中文JSON序列化后呈现乱码（如“，”或方块、问号）

开发者调用 QJsonDocument::toJson() 得到 QByteArray，写入文件或发送至 HTTP 客户端后，中文显示为 ，、、或 Moji-Bake 字符。此为表层症状，非根本原因。

二、编码链路层：Qt UTF-8 默认策略与实际 I/O 编码的隐式脱节

• Qt 5.0+ 中 QString 内部以 UTF-16 存储，但 QJsonDocument::toJson() 返回的 QByteArray 始终为 UTF-8 编码（无 BOM）；
• 问题常发于后续操作：若用 QTextStream 写入文件却未调用 setCodec("UTF-8")，其默认使用 QTextCodec::codecForLocale()（可能为 GBK/Shift-JIS）；
• 同理，QFile 本身无编码概念，仅当配合 QTextStream 使用时才引入编码歧义。

三、数据源头层：非 UTF-8 输入污染 JSON 构建过程

输入来源	典型风险场景	后果
GBK 编码文本文件	QFile → QTextStream → readAll() 未指定 codec	QString 含乱码字符，嵌入 JSON 后整个 value 变为非法 UTF-8 序列
Windows 控制台 argv	未通过 QString::fromLocal8Bit() 转换	中文参数被截断或误解为 Latin-1

四、传输协议层：HTTP 头缺失导致接收端编码误判

即使 JSON 内容为纯 UTF-8，若 REST API 响应头缺失：
Content-Type: application/json; charset=utf-8， 则浏览器、curl 或 Python requests 等客户端可能按 ISO-8859-1 或系统 locale 解码，触发二次乱码。

五、架构决策层：弃用过时 API，确立 UTF-8 单一真相源

// ❌ 危险：已废弃，全局污染编码上下文
QTextCodec::setCodecForLocale(QTextCodec::codecForName("GBK"));

// ✅ 推荐：显式、局部、可审计
QTextStream out(&file);
out.setCodec("UTF-8"); // 强制 UTF-8
out << doc.toJson(QJsonDocument::Compact);

六、验证闭环：十六进制字节级确认 UTF-8 合法性

调试关键代码段：

QByteArray jsonBytes = doc.toJson(QJsonDocument::Compact);
qDebug() << "Hex:" << jsonBytes.toHex(); // 如“中文”→ e4 b8 ad e6 96 87
qDebug() << "Has BOM?" << jsonBytes.startsWith("\xEF\xBB\xBF");
// 若出现 c0 af、a3 ac 等非标准 UTF-8 字节，则源头已污染

七、工程实践规范：四步防御体系

1. 输入净化：所有外部字符串（文件、argv、网络包）必须经 QString::fromUtf8() 或 fromLocal8Bit() 显式转换；
2. 序列化直出：优先用 QJsonDocument::toJson() 返回 QByteArray，避免经 QTextStream 中转；
3. 落盘/传输加固：文件写入前 QTextStream::setCodec("UTF-8")；HTTP 响应头强制设置 charset=utf-8；
4. CI 自动校验：在单元测试中对 JSON 输出执行 QTextDecoder("UTF-8").toUnicode(jsonBytes) 并断言无替换字符（）。

八、深度诊断流程图（Mermaid）

graph TD
  A[发现中文乱码] --> B{是否检查 toUtf8().toHex()?}
  B -- 是 --> C[确认字节为合法 UTF-8？]
  B -- 否 --> D[立即添加 hex 日志]
  C -- 否 --> E[溯源 QString 构造方式：fromUtf8? fromLocal8Bit?]
  C -- 是 --> F[检查输出端：QTextStream.codec? HTTP header?]
  E --> G[修复输入解码逻辑]
  F --> H[统一设 UTF-8 codec / header]
  G --> I[回归测试]
  H --> I

```