Qt默认编码非UTF-8，中文乱码如何统一设置为UTF-8？

Question

在Windows平台使用Qt（尤其Qt5.14之前版本）时，常因系统默认编码为GBK/GB2312，而Qt内部字符串处理依赖`QTextCodec::setCodecForLocale()`（已弃用）或未显式设置UTF-8，导致中文字符串在`QString`构造、文件读写、网络响应解析、控件显示等环节出现乱码。典型现象包括：源码中硬编码中文显示为“?”、`.ui`文件内中文正常但动态设置的`QLabel::setText("你好")`显示异常、`QFile`读取UTF-8文本时中文变方块。该问题本质是Qt对本地编码（`QLocale::system().name()`）与实际文本编码（如UTF-8）的映射不一致所致。虽Qt6已默认全面转向UTF-8，但在大量存量Qt5项目中，仍需通过统一入口（如`main()`函数首行）强制设置`QTextCodec::setCodecForUtf8()`（Qt5.10+）或`QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8"))`（旧版），并配合源文件保存为UTF-8 with BOM（Windows下兼容性更稳）、`.pro`中添加`CODECFORSRC = UTF-8`等措施协同解决。

Answer 1

```html

一、现象层：乱码的典型表征与场景归类

• 源码硬编码失效：如 QLabel::setText("你好") 在 Windows 控制台或界面中显示为 "??" 或空方块；
• .ui 文件“幸存”但动态文本崩塌：Qt Designer 保存的中文在 UI 加载时正常，但运行时 label->setText(tr("设置")) 却乱码——说明 tr() 未生效或编码链断裂；
• QFile 读取 UTF-8 文本失败：含中文的 JSON/INI 文件用 QFile::readAll() 后，QString::toUtf8() 输出异常字节，QString::length() 错误计数；
• 网络响应解析失真：HTTP 返回 UTF-8 响应体（如 {"msg":"成功"}），经 QJsonDocument::fromJson() 后 msg 字段显示为乱码；
• 日志与调试输出错乱：qDebug() << QString::fromLocal8Bit("测试") 反而正确，而直接输出中文字符串却失败——暴露默认构造器隐式调用本地编码。

二、机制层：Qt5 字符串编码模型与 Windows 环境冲突图谱

Qt5 的字符串抽象基于 QString（UTF-16 存储），但其与外部世界的编解码桥接依赖三类关键接口：

接口类型	Qt 版本支持	作用域	Windows 默认行为风险
QTextCodec::setCodecForLocale()	Qt4.8–Qt5.9（已弃用）	影响 QString::fromLocal8Bit()、toLocal8Bit()、QFile 默认编码	绑定 GBK，导致 UTF-8 源码被误解为 GBK → 多字节截断
QTextCodec::setCodecForUtf8(true)	Qt5.10+（推荐）	强制 fromUtf8()/toUtf8() 成为默认路径，覆盖 locale 逻辑	需配合源文件真实编码，否则仍失败

三、根因层：编码契约断裂的四大断点

1. 源文件编码 ≠ Qt 解析预期：ANSI（GBK）保存的 .cpp 在 Qt5.10+ 中被 CODECFORSRC = UTF-8 强制按 UTF-8 解析 → 字节流错位；
2. QLocale::system().name() 返回 "zh_CN"，但 Qt 未自动映射到 UTF-8（Qt5 不同于 glibc/Linux），仍走 QTextCodec 查表逻辑；
3. QFile 默认使用 locale codec，而非 BOM 检测或显式声明，读取无 BOM 的 UTF-8 文件即失败；
4. tr() 翻译系统依赖 .qm 文件编码 + 源码编码一致性，若 .ts 导出为 UTF-8 但源码为 GBK，则运行时 tr("Save") 查不到键。

四、工程层：五维协同治理方案（适配 Qt5.14−）

graph LR A[main.cpp 首行] --> B[QTextCodec::setCodecForUtf8 true] B --> C[.pro 添加 CODECFORSRC = UTF-8] C --> D[所有源文件存为 UTF-8 with BOM] D --> E[QFile 显式指定 codec
file.setCodec(“UTF-8”)] E --> F[网络响应强制 fromUtf8
QString::fromUtf8(reply->readAll())]

五、验证层：可落地的诊断检查清单

• ✅ 运行 qDebug() << QLocale::system().name() << QTextCodec::codecForLocale()->name(); 确认是否仍为 GBK；
• ✅ 用 VS Code / Notepad++ 检查 main.cpp 文件属性：必须显示 “UTF-8 with BOM”；
• ✅ 在 main() 中插入：QTextStream out(stdout); out.setCodec("UTF-8"); out << "✓ 编码就绪\n";；
• ✅ 对 QFile 操作前加：file.setCodec("UTF-8"); if (!file.open(QIODevice::ReadOnly)) { /*log error*/ }；
• ✅ 使用 QStringLiteral 替代裸字符串字面量（Qt5.10+ 编译期转 UTF-16，绕过运行时 codec）。

六、演进层：从 Qt5 到 Qt6 的编码范式迁移启示

Qt6 彻底移除 QTextCodec 全家桶，QString::fromUtf8() 成为唯一标准入口，QFile 默认 UTF-8，.pro 中 CODECFORSRC 废止。这反向印证：Qt5 的乱码本质不是“bug”，而是设计上对多编码生态的过渡性妥协。存量项目升级时，应将编码治理作为重构第一关卡——它比信号槽优化或线程模型调整更具底层穿透力。

```