本章重要 API 函数#

💡 Tips：最易错的是构造函数的隐式编码假设——QString("中文") 把字面量当 UTF-8。若你的源文件保存为 GBK（Windows 老工程常见），编译器把 GBK 字节塞进字面量，QString 却按 UTF-8 解，立刻乱码。Qt5/Qt6 一致：源码应是 UTF-8，并在 .pro/CMake 里声明 UTF-8 编码。

本章目录#

点击条目可跳转到对应小节。

学习前后依赖#

💡 Tips：编码问题是 Qt 初学者”中文一堆问号”的头号元凶。本章必须先于任何带中文 UI 的章节——否则你会在 qt11 按钮上看到”????”，却不知道是 QString::fromLocal8Bit 用错了。先会 qt10 的 char/string，再学本章转换，顺序不能反。

1. 概述#

C++ 原生的 char* 和 std::string 不携带编码信息——它们只是一串字节。char* 字面量 "你好" 在内存里到底是 UTF-8 的 6 个字节还是 GBK 的 4 个字节，完全取决于源文件保存时的编码。而 Qt 的 QString 内部统一使用 UTF-16（Qt6 内部是 char16_t，每个 QChar 占 2 字节，基本多文种平面 BMP 内一个字符一 QChar，辅助平面用代理对）。这个”内部统一 Unicode、对外灵活编解码”的设计，让 Qt 能正确处理全世界文字，但也带来一个绕不开的问题：QString 与外部 char*/std::string 之间如何转换，才不会乱码？

qt09 用三个测试函数给出答案：test01 对比 char*、std::string、QString 三种字符串的打印；test02 揭示 QString 的”写时复制/隐式共享”内部指针；test03 演示 asprintf 与 arg() 两种格式化，并在注释块里给出 fromUtf8/toUtf8 的真实用法。理解它们，你就掌握了 Qt 世界里”字符串从哪来、到哪去”。

💡 Tips：概述里最该记住的一句话——“QString 内部永远是 UTF-16；你和它之间只隔着一次明确的编解码，编码说不清，乱码就来了。” 不存在”QString 直接存了 UTF-8”这回事。

2. 核心概念 / 原理#

3. 编码转换链路#

下面用 flowchart 画出 char* 与 QString 之间双向转换的四条链路：

关键规则：黄框 QString 是唯一”懂 Unicode”的节点，所有箭头进出它都必须声明编解码方式。灰框 char*/std::string/QByteArray 都是”裸字节”，它们自己不知道自己是什么编码。

💡 Tips：流程里最关键的箭头是 A -->|QString(str) = fromUtf8 默认| B——它默认 UTF-8。一旦你机器上的源文件不是 UTF-8（比如 Windows 记事本存成 ANSI/GBK），这条默认箭头就会把 GBK 字节当 UTF-8 解，直接乱码。判断乱码根因，就盯住每个”裸字节 → QString”的箭头用了哪种解码。

4. 核心代码解析#

qt09_tst-QString-char_/main.cpp 三段测试，逐段看：

1
void test01() {
2
    const char *str1 = "hello你好";
3
    std::string str2 = "hello你好";
4
    QString str3 = "hello你好";     // 等同 fromUtf8(str1)
5

6
    cout << str1 << endl;           // 依赖终端编码：终端是 UTF-8 才正常
7
    cout << str2 << endl;           // 同 str1，std::string 原样字节
8
    qDebug() << str3;               // qDebug 自己按 Unicode 输出，最稳
9
}

• str3 = "hello你好" 走 QString(const char*)，被当 UTF-8 解码。qDebug() << str3 永远正确，因为 qDebug 直接操作内部 UTF-16；而 cout << str1 是否正确，取决于终端/控制台的编码是否也是 UTF-8（Windows 老控制台默认 GBK，就会乱）。

1
void test02() {
2
    QString x1 = "12345";
3
    QString x2(x1);                 // 拷贝，隐式共享
4
    qDebug() << x1.data_ptr().d_ptr() << x2.data_ptr().d_ptr(); // 同地址
5
    x2[1] = 'w';                    // 发生写时复制 detach
6
    qDebug() << x1.data_ptr().d_ptr() << x2.data_ptr().d_ptr(); // 地址不同
7
}

• 拷贝构造后 x1、x2 的 d_ptr()（底层数据指针）相同，证明共享；x2[1]='w' 触发 detach，之后两者指向不同内存。这就是隐式共享：拷贝很廉价，修改才付代价。

1
void test03() {
2
    const char *fmt1 = "My name is %s, I'm %d years old, %d is too young!\n";
3
    qDebug() << QString::asprintf(fmt1, "rocky", 18, 18);   // C 风格
4
    QString qfmt2("My name is %1, I'm %2 years old, %2 is too young!\n");
5
    qDebug() << qfmt2.arg("rocky").arg(16);                 // Qt 位置参数 %1 %2
6
    // 注释块中给出：
7
    // QString::fromUtf8(buf1, strlen(buf1));
8
    // str1.toUtf8().constData();   // QString -> UTF-8 字节
9
}

• asprintf 是 C 风格 sprintf 的安全版；arg() 用 %1 %2 位置占位，可重复引用（如 %2 出现两次都填 16），比 C 风格更易维护、支持 Unicode 更友好。
• 注释块里的 fromUtf8 / toUtf8().constData() 正是本章核心转换 API 的真实用例，虽被 #if 0 关掉，但展示了”字节 → QString → 字节”的闭环。

💡 Tips：这段代码藏着的细节——① x2[1]='w' 的 operator[] 非 const 版本才会 detach，若用 x2.at(1) 只读则不分离；② arg() 是返回新 QString 的链式调用，qfmt2 本身不变；③ toUtf8().constData() 返回的指针只在 QByteArray 临时对象存活期内有效，别把它存成长期 char* 否则悬空。

5. 运行效果 / 验证#

编译运行 qt09，预期：

• test01：qDebug() << str3 稳定打印 hello你好；cout 是否在控制台也正常，取决于终端编码（Windows 下可能显示乱码，但 QString 本身是对的）。
• test02：修改前 x1、x2 的 d_ptr() 输出相同地址；x2[1]='w' 后输出不同地址，且 x1 仍是 "12345"、x2 变 "1w345"（验证写时复制只影响副本）。
• test03：asprintf 与 arg() 都正确填入参数。

💡 Tips：验证时最容易误判”成功”的假象——在 qDebug 里看到中文正常，就以为全链路没问题。但 qDebug 走的是内部 UTF-16 直接输出，掩盖了 cout/文件/网络那一层编码问题。真正该验证的是：把 QString 用 toUtf8() 写出文件、用十六进制查看器确认是 e4 bd a0 e6 88 91（“你好”的 UTF-8），这才是编码正确的铁证。

容易踩坑（注意点）#

• 坑 1：源文件非 UTF-8 导致 QString("中文") 乱码。现象：界面/日志出现”涓­“类乱码。原因：字面量被当 UTF-8 解，但字节实为 GBK。规避：编辑器保存为 UTF-8（无 BOM 亦可），Qt6 默认按 UTF-8 读源码；必要时改用 QString::fromLocal8Bit("中文")。
• 坑 2：toLocal8Bit().constData() 悬空指针。现象：拿到的 char* 很快变成垃圾值。原因：QByteArray 是临时对象，语句结束即析构，指针失效。规避：先存到具名 QByteArray ba = str.toUtf8(); const char* p = ba.constData(); 延长生命周期。
• 坑 3：用 qPrintable() 与 toLocal8Bit() 混用。现象：跨平台中文时好时坏。原因：qPrintable 本质 toLocal8Bit().constData()，依赖本地编码，在 Linux(UTF-8)/Windows(GBK) 行为不一致。规避：需要 const char* 时优先 toUtf8().constData() 并明确接收方按 UTF-8 解释。
• 坑 4：std::string 经 fromStdString 乱码。现象：网络/文件读入的 GBK std::string 转 QString 乱。原因：fromStdString 默认当 UTF-8。规避：若源是本地编码用 QString::fromLocal8Bit(s.c_str())。
• 坑 5：认为 QString 存的是 UTF-8。现象：调试时直接读内存找 UTF-8 字节找不到。原因：内部是 UTF-16。规避：需要 UTF-8 字节必须显式 toUtf8()。

学习要点总结#

Q&A（常见问题）#

Q1：为什么 qDebug() << str 正常，但 cout << str 乱码？ A1：qDebug 直接操作 QString 内部 UTF-16，按 Unicode 输出，与终端无关；cout << str1 输出的是 char* 裸字节，由控制台编码决定显示。Windows 老控制台默认 GBK，而字面量是 UTF-8 字节，所以乱。解决：让控制台用 UTF-8（chcp 65001），或统一用 qDebug。

Q2：toUtf8() 和 toLocal8Bit() 该用哪个？ A2：与外部交互（文件、网络、跨平台）一律 toUtf8()，因为 UTF-8 是事实标准、跨平台一致。只有调用”只认系统本地编码”的老 C/Windows API（如某些 char* 接口、老 DLL）才用 toLocal8Bit()。优先 UTF-8，本地编码是例外。

Q3：Qt5 和 Qt6 在 QString 上有差异吗？ A3：转换 API 基本一致。主要差异：Qt6 把内部存储从 ushort 改为 char16_t，QChar 行为微调；删除了 QString::null 等旧常量，用 QString() 空串代替；QStringRef 改为 QStringView（C++17 string_view 风格，零拷贝）。编码核心（fromUtf8/toUtf8）两版完全相同。

Tips（全局速记）#