Qt 高级开发 017：中文乱码

[Bilibili 同步视频](#Bilibili 同步视频)
[一、乱码的根源：Qt 对中文支持的先天不足](#一、乱码的根源：Qt 对中文支持的先天不足)
二、不同开发环境下的乱码表现与初步尝试
- [2.1 Qt Creator 环境：变幻莫测的编码行为](#2.1 Qt Creator 环境：变幻莫测的编码行为)
- [2.2 Visual Studio 环境：相对可控的解决方案](#2.2 Visual Studio 环境：相对可控的解决方案)
- [方案一：使用 u8 前缀指定 UTF-8 编码](#方案一：使用 u8 前缀指定 UTF-8 编码)
- 方案二：设置编译器执行字符集
三、那些年我们踩过的编码坑
- [3.1 u8 前缀的局限性](#3.1 u8 前缀的局限性)
- [3.2 BOM 头的爱恨情仇](#3.2 BOM 头的爱恨情仇)
- [3.3 编码转换的误区](#3.3 编码转换的误区)
四、终极解决方案：从根源规避乱码
- [4.1 代码层面：全英文标识符与字符串](#4.1 代码层面：全英文标识符与字符串)
- [4.2 项目层面：Qt 国际化翻译系统](#4.2 项目层面：Qt 国际化翻译系统)
五、开发工具选择的小建议
结语：写在最后

Bilibili 同步视频

Qt 高级开发 017：中文乱码

在 Qt 开发的漫漫长路上，中文乱码就像一个挥之不去的幽灵，时常在你最意想不到的时候跳出来捣乱。明明代码写得毫无破绽，编译运行后却只看到一堆乱码方块，那种挫败感相信每一位 Qt 开发者都深有体会。今天，我们就来深入剖析这个顽疾的根源，梳理各种解决方案的优劣，最终找到一套能彻底规避乱码问题的最佳实践。

一、乱码的根源：Qt 对中文支持的先天不足

★ 核心问题：Qt 框架本身对中文的支持存在一定的局限性，这是导致中文乱码频发的根本原因。

在实际开发中，我们经常会遇到以下几种典型的乱码场景：

常量字符串中包含中文时出现乱码
换行符与中文字符混合时出现乱码
不同开发环境之间代码迁移时出现乱码
相同代码在不同编译配置下表现不一致

这些问题的本质，是字符编码在编辑器→编译器→运行时这三个环节中出现了不匹配。而 Qt 的跨平台特性，使得编码问题变得更加复杂 ------ 不同操作系统的默认编码不同，不同编译器的字符集处理方式也不同，最终导致了乱码问题的 "千奇百怪"。

二、不同开发环境下的乱码表现与初步尝试

2.1 Qt Creator 环境：变幻莫测的编码行为

▶ 测试过程：

创建一个全新的 Qt Widgets 项目
在 UI 设计器中拖入一个 QPushButton 控件
使用setText()方法设置中文文本
编译运行，观察结果

⚠️ 令人困惑的现象：

有时候直接写中文完全正常，没有任何乱码
有时候同样的代码却会出现乱码
修改文本编辑器的编码设置（UTF-8，总是添加 / 删除 BOM）后，结果依然不稳定
清除构建目录重新编译，有时能解决问题，有时却毫无效果
将代码从其他环境复制粘贴过来后，乱码问题会突然出现

我们甚至尝试过将文件编码切换为 GB2312（中文系统的传统编码），但结果依然不尽如人意 ------ 乱码问题并没有得到根本解决，反而引入了新的兼容性问题。

2.2 Visual Studio 环境：相对可控的解决方案

▶ 测试过程：

在 Visual Studio 中创建 Qt Application 项目
同样添加一个 QPushButton 控件
设置中文文本后编译运行

⚠️ 结果：必然出现中文乱码

不过，在 Visual Studio 环境中，我们找到了两种相对可靠的临时解决方案：

方案一：使用 u8 前缀指定 UTF-8 编码

cpp 复制代码

#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    QPushButton btn;
    
    // 使用u8前缀告诉编译器：这个字符串字面量采用UTF-8编码
    btn.setText(u8"点击我试试");
    
    btn.show();
    return a.exec();
}

✅ 效果：几乎能 100% 解决 Visual Studio 中的中文乱码问题

方案二：设置编译器执行字符集

cpp 复制代码

// 这行代码必须放在所有#include指令之前
#pragma execution_character_set("utf-8")

#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    QPushButton btn;
    
    // 不需要u8前缀，直接使用中文即可
    btn.setText("点击我试试");
    
    btn.show();
    return a.exec();
}

✅ 效果：全局生效，无需为每个中文字符串添加 u8 前缀

三、那些年我们踩过的编码坑

3.1 u8 前缀的局限性

⚠️ 重要提醒：u8 前缀并不是万能的！

在 Qt Creator 环境中，我们发现了一个非常诡异的现象：

有时候添加 u8 前缀能解决乱码
有时候添加 u8 前缀反而会出现乱码
有时候去掉 u8 前缀，乱码又神奇地消失了

这种不稳定的表现，让 u8 前缀只能作为一种临时解决方案，而不能作为通用的最佳实践。

3.2 BOM 头的爱恨情仇

BOM（Byte Order Mark）是 UTF-8 文件开头的一个特殊标记，用于标识文件的编码格式。在 Qt Creator 中，我们可以在文本编辑器的设置中选择 "总是添加 BOM" 或 "总是删除 BOM"。

然而，经过多次测试我们发现：

无论选择哪种设置，都无法保证 100% 避免乱码
不同版本的 Qt Creator 对 BOM 的处理方式不同
跨平台开发时，BOM 头可能会导致新的问题

3.3 编码转换的误区

很多开发者遇到乱码时，第一反应就是进行编码转换，比如使用QString::fromLocal8Bit()或QString::fromUtf8()等方法。

⚠️ 这种做法存在两个严重的问题：

代码变得臃肿且难以维护
不同环境下的本地编码不同，导致代码的可移植性极差
治标不治本，无法从根源上解决乱码问题

四、终极解决方案：从根源规避乱码

经过无数次的尝试和踩坑，我们终于得出了一个结论：与其在乱码出现后想方设法去解决，不如从一开始就彻底规避乱码问题。

4.1 代码层面：全英文标识符与字符串

★ 最佳实践：所有代码都使用英文编写

这是最简单、最可靠、最一劳永逸的解决方案。具体来说：

所有变量名、函数名、类名都使用英文
所有字符串字面量都使用英文
避免在代码中直接出现任何中文字符

这样做的好处是显而易见的：

彻底消除了中文乱码的可能性
代码的可移植性大大提高
符合国际编程规范，便于团队协作和代码维护

4.2 项目层面：Qt 国际化翻译系统

当项目需要显示中文界面时，我们应该使用 Qt 官方提供的国际化翻译系统，而不是直接在代码中写中文。

Qt 的翻译系统工作流程如下：

在代码中使用tr()函数包裹所有需要翻译的字符串
使用lupdate工具从源代码中提取所有待翻译的字符串，生成.ts文件
使用 Qt Linguist 工具打开.ts文件，进行翻译
使用lrelease工具将翻译好的.ts文件编译成.qm文件
在程序运行时加载对应的.qm文件

示例代码：

cpp 复制代码

#include <QApplication>
#include <QPushButton>
#include <QTranslator>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    
    // 加载翻译文件
    QTranslator translator;
    if (translator.load(":/translations/zh_CN.qm")) {
        a.installTranslator(&translator);
    }
    
    QPushButton btn;
    // 使用tr()函数包裹需要翻译的字符串
    btn.setText(QObject::tr("Click Me"));
    
    btn.show();
    return a.exec();
}

这种方法的优势非常明显：

彻底解决了中文乱码问题
轻松支持多语言切换
界面文本与代码分离，便于后期维护
符合 Qt 的设计理念和最佳实践

很多知名的 Qt 应用（如 MindMaster 思维导图软件）都是采用这种方式来处理多语言的。我们可以在它们的安装目录下找到translation文件夹，里面存放着各种语言的.qm翻译文件。

五、开发工具选择的小建议

★ 经验分享：优先选择 base 开发环境

在实际开发中，我们发现不同的开发工具在处理 Qt 编码问题时表现差异很大：

Qt Creator：编码行为复杂多变，乱码问题频发，排查困难
base 开发环境：编码处理相对稳定，乱码问题较少，即使出现乱码，通过添加 u8 前缀或设置执行字符集一般都能解决

因此，如果你深受 Qt 中文乱码问题的困扰，不妨尝试切换到 base 开发环境，或许能让你的开发效率大大提升。

结语：写在最后

═══════════════════════════════════════════

Qt 中文乱码问题，看似是一个小问题，却困扰了无数开发者。很多人在这个问题上浪费了大量的时间和精力，却依然没有找到完美的解决方案。

通过今天的深度探索，我们明白了：乱码问题的根源在于编码的不匹配，而最好的解决方案不是去 "修复" 乱码，而是从一开始就避免乱码的产生。使用全英文编写代码，配合 Qt 的国际化翻译系统，不仅能彻底解决中文乱码问题，还能让你的代码更加规范、更加可维护、更加国际化。

当然，Qt 的编码问题还有很多细节值得我们去深入研究。比如.ts文件的详细编辑方法、多语言切换的高级技巧、不同平台下的翻译文件加载策略等等。后续我会继续分享这些内容，帮助大家彻底攻克 Qt 开发中的各种难题。

愿每一位 Qt 开发者都能摆脱乱码的困扰，专注于创造更优秀的软件产品！