企业官网建设流程全解析

Qt 文本文件读写这件事，说简单也简单，QFile加QTextStream六行代码就能跑通；说麻烦也麻烦，等用户发来一个 GBK 编码的 CSV、一个三百兆的日志、或者一个带\r换行的 txt，乱码、丢行、卡界面就全来了。我做了几年桌面端工具，文本文件读写写过的次数自己都数不清，从早期QFile+readAll的暴力流，到后来按场景拆成配置文件、数据文件、日志三套不同的写法，踩的坑基本集中在编码、换行、原子性和性能这四件事上。

这篇内容不打算讲 API 手册，那些东西官方文档写得更全。我要聊的是：一个真实项目里，文本文件读写该怎么分工、怎么选接口、怎么处理中文、怎么防止写坏文件、怎么在几百万行的文件上不把内存撑爆。适合刚上手 Qt 不久、能看懂基本 C++ 的同学，也适合写了两三年但一直用“能跑就行”的方式读写文件的同学。代码默认以 Qt 6 为主，涉及 Qt 5 的差异我会单独标出来，因为现在还有大量项目卡在 Qt 5.15 上没动。

1. 先想清楚你读的到底是什么文件

1.1 文本文件在工程里至少有四种截然不同的面孔

很多人写读写代码出问题，根子不在 API，而在一开始就没给文件分类。我把项目里遇到的文本文件粗分成四类：第一类是配置文件，ini、json、yaml 这些，特点是小，几十 KB 顶天，一次全读进内存解析完事，改完整体覆盖写回；第二类是数据文件，CSV、TSV、导出的报表、采集日志，特点是可能很大，从几 MB 到几 GB 都有，必须逐行或者分块处理；第三类是给用户看的纯文本，比如快捷键说明、许可证文本、模板片段，这类文件往往是人工编辑的，编码和换行符完全不受你控制；第四类是程序自产自销的中间文件，自己写自己读，编码、换行、格式都能自己定，最省心。

这四类的处理策略差得很远。配置文件可以无脑readAll然后QJsonDocument::fromJson，因为文件小到内存根本不在乎；数据文件如果用readAll，一个 500MB 的日志进来就是 500MB 的QByteArray，再split成QStringList内存还要翻三到五倍，32 位程序当场就崩了；用户可见的纯文本则必须做编码兜底，因为你永远不知道用户用什么编辑器存的。我见过一个项目，把所有文本都走同一条readAll + split("\n")的路，结果导出一个 200MB 的表格直接 OOM，查了半天才发现问题在这个“顺手”的函数上。

1.2 QFile、QTextStream、QDataStream 各自站的位置

Qt 在文件这块给的三个主要角色，职责其实划得很清楚，只是新手容易拿来就用。

QFile是所有文件操作的底座，它本质上是QIODevice的一个实现，给你的是字节流。QTextStream是包在QFile外面的一层适配器，负责把字节按编码解成QString，再按行、按字段切出来，同时把QString按编码写回字节。QDataStream走的是另一条路，它做的是二进制序列化，带类型和字节序信息，跟“文本文件读写”基本不是一回事，只有在你需要存自己的二进制格式时才用得上。

我个人的默认选择是这样的：配置文件和数据文件的解析逻辑，一律先用QFile拿到字节，再交给专门的解析器（JSON、CSV 库），因为那些解析器本身接受QByteArray；只有需要逐行处理纯文本、或者需要按行做业务判断时，才上QTextStream。这个分工看起来保守，但它把“字节层”和“字符层”分开了，后面排查乱码问题时会轻松很多。

2. QFile 裸读和 QTextStream 逐行的取舍逻辑

2.1 QFile 直接 readLine 的适用场合

QFile自己带readLine()，返回QByteArray，包含行尾的换行符。这个接口最大的价值是不经过字符解码，你拿到的是原始字节，可以自己决定怎么解、用哪种编码解，也可以直接对字节做模式匹配。我在处理日志过滤这种任务时基本都用它，因为日志天然按行组织，而我要做的是“找包含某关键字的行”，根本不需要先把整行解成QString——直接用QByteArray::contains在字节上匹配 UTF-8 序列会更快，命中了再解码。

用readLine有个必须注意的点：返回的字节里带着换行符，Linux 和 macOS 上是\n，Windows 上是\r\n。如果你后面要按行拼装或做哈希，就得手动剥掉。剥的顺序有讲究，先剥\n再剥\r，反过来的话\r\n会留下一个孤零零的\n：

QByteArray line = f.readLine(); if (line.endsWith('\n')) line.chop(1); if (line.endsWith('\r')) line.chop(1); // 顺序不能反

还有一点，文件最后一行如果没有换行符，readLine也会正常返回这一行的内容，不会丢。但如果你用“读到的行是否为空”来判结束，就会把文件末尾的一个空行误判成 EOF。判断结束一律用f.atEnd()，不要用内容判断。

2.2 QTextStream 帮你省掉的活

QTextStream真正值钱的地方有三个。第一是编码解码，你把文件按QIODevice::ReadOnly | QIODevice::Text打开，构造QTextStream并设置编码，读出来的就是QString，不用自己管字节。第二是流式操作符，ts >> word >> number这种写法在读“结构规整但用空格分隔”的文本时特别省事，配合setIntegerBase、setRealNumberPrecision还能控制数字解析和格式化的细节。第三是写侧的统一，ts << "名称: " << name << Qt::endl，不同类型混着写不用手动转字符串，这对生成人眼可读的报表很友好。

但QTextStream有两个坑必须提前知道。第一个是数字格式化受 locale 影响。QTextStream在把double转成字符串时会参考 locale，某些环境下小数点会变成逗号——写 CSV 时这一条足以毁掉整个文件，因为下游解析器会把3,14当成两列。解决办法是显式指定：

QTextStream ts(&file); ts.setLocale(QLocale::c()); // 强制用点号做小数点，写 CSV 必加

第二个坑是QTextStream::atEnd()在流式读取时的历史行为不够可靠，社区里也有不少讨论，某些版本上它需要先尝试读取才会更新内部状态。稳妥的做法是用QFile::atEnd()做循环条件，用QTextStream::readLine()取行，两者组合起来最稳：

QFile f(path); if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) { // 处理错误 } QTextStream ts(&f); ts.setEncoding(QStringConverter::Utf8); // Qt 6 写法 // Qt 5 写成：ts.setCodec("UTF-8"); QString line; while (!f.atEnd()) { line = ts.readLine(); // 业务处理 }

2.3 QIODevice::Text 这个标志到底改了什么

几乎所有的 Qt 文件读写示例里都会带上QIODevice::Text，但很少有人讲清楚它干了什么。它的作用是在读取时把平台相关的行尾统一转成\n：在 Windows 上读到的\r\n会变成\n，Linux 上读到什么就是什么。写侧的行为则相反，它会让\n按照平台习惯输出。这个转换让“同一份代码跨平台读文本”变得可行，代价是你拿到的字节已经不是磁盘上的原始字节了。

所以选择很简单：文本文件用QIODevice::Text，二进制文件绝对不用。二进制文件里如果碰巧有0x0D 0x0A这种字节组合，加了Text标志就会被改掉，读取结果直接损坏。我见过有人读一个自定义格式文件时顺手加了Text，结果只有在 Windows 上能复现的数据错乱，查了两天才定位到这个标志上。

3. 中文乱码的根因和编码处理方案

3.1 UTF-8、BOM 与本地代码页三者的关系

中文乱码这件事，本质是两个问题叠在一起：文件实际用的编码，和你解码时假定的编码不一致。既然解码假定的编码是我们自己定的，那正确的做法就是不要假定，而是先探测。

UTF-8 是现在的默认选项，Qt 的字符串字面量、JSON、大多数现代工具链都默认 UTF-8。但 UTF-8 有个历史包袱叫 BOM，也就是文件开头那三个字节EF BB BF。BOM 对 UTF-8 来说毫无必要，但 Windows 上很多编辑器（尤其是记事本系）会写。BOM 带来的典型问题是：你按 UTF-8 读第一行，第一个字符会变成一个看不见的U+FEFF，如果这行是 JSON 的{或者 CSV 的表头，下游解析就报错了。所以读文件时必须做 BOM 剥离，写文件时默认不写 BOM。

“本地代码页”是另一个世界。简体中文 Windows 的默认 ANSI 代码页是 936，也就是很多人说的 GBK。用户在旧版本 Excel 里导出 CSV，或者用某些国产编辑器保存 txt，产出的就是 GBK 文件。GBK 用两个字节表示一个汉字，跟 UTF-8 的三字节编码完全不兼容，用 UTF-8 去解 GBK 会得到一堆问号和方块，反之则是一串看不懂的西欧字符。

顺带说一个应用层的现实：写 CSV 时加不加 BOM 是个产品决策，不是技术决策。如果你导出的 CSV 是给用户用 Excel 直接打开的，不加 BOM 的话，新版 Excel 可能把中文识别成乱码；加了 BOM，Excel 就正常了，但你的程序读自己的文件时又得处理 BOM。我一般的处理是：导出给用户看的 CSV 加 BOM，程序内部流转的数据文件不加 BOM，读取端一律做 BOM 兼容。

3.2 Qt 5 和 Qt 6 编码 API 的迁移对照

这块是升级 Qt 6 时踩得最多的雷。Qt 6 把QTextCodec从核心模块里拿掉了，换成了QStringConverter/QStringDecoder/QStringEncoder三件套，但新接口支持的编码数量比老的少得多。对照关系大概是这样的：

QStringConverter内置的编码枚举只有 UTF-8、UTF-16、UTF-32、Latin-1 和 System 这几种。要在 Qt 6 下处理 GBK，实践中有三条路，我按推荐度排序：第一，如果目标平台是简体中文 Windows，直接用QStringConverter::System，它在 Windows 上会走系统代码页，中文环境下就是 936，能解 GBK；第二，引用Qt5Compat模块，继续用QTextCodec，工程文件里加QT += core5compat（CMake 里是find_package(Qt6 COMPONENTS Core5Compat REQUIRED)加链接），迁移成本最低；第三，接入iconv这类系统库自己转换，适合跨平台但目标系统编码不确定的场景，代价是要写平台相关的条件编译。

第三种我一般不推荐，除非你确实要处理多种非 UTF 编码且不能依赖系统环境。绝大多数国内项目的真实需求是“让用户能打开 GBK 的老文件”，用第一条或第二条就够了。

3.3 一个先探测再解码的读取流程

把上面的东西串起来，一个稳妥的读取流程是这样的：先读文件开头几十个字节，判断有没有 BOM，确定高置信度的编码；如果没有 BOM，就尝试用 UTF-8 解码这一小段，检查是否出现解码错误或替换字符，出现了就退回本地编码；确定编码之后，再按确定好的解码器去读正文。

BOM 判断部分非常简单：

static QString sniffBom(const QByteArray &head) { if (head.startsWith("\xEF\xBB\xBF")) return QStringLiteral("utf-8-bom"); if (head.startsWith("\xFF\xFE")) return QStringLiteral("utf-16le"); if (head.startsWith("\xFE\xFF")) return QStringLiteral("utf-16be"); return QString(); // 没有 BOM，需要进一步判断 }

UTF-8 合法性检测在 Qt 6 下可以用QStringDecoder的hasError()：

static bool looksLikeUtf8(const QByteArray &sample) { QStringDecoder dec(QStringConverter::Utf8); const QString s = dec(sample); return !dec.hasError() && !s.contains(QChar(0xFFFD)); }

Qt 5 下等价的做法是用QTextCodec配合QTextCodec::ConverterState，把状态对象传进toUnicode，然后检查state.invalidChars是否为零。写法比 Qt 6 啰嗦一些，但逻辑一样。

提示：探测只针对“用户给的、编码未知的文件”。程序自己产出的文件，编码写死 UTF-8 就行，不要加探测逻辑，那只是白白增加分支和误判概率。

4. 从零搭一个够用的文本读写模块

4.1 接口设计：先把错误返回方式定下来

写这类工具模块，我踩过的最大坑不是技术问题，是接口设计问题。一开始图省事，函数返回QStringList，读失败就返回空列表——结果调用方根本分不清“文件是空的”和“文件打不开”。这种模糊接口在项目里流传两年之后，会变成几十处无法排查的静默失败。

我现在的做法固定成三条：返回值只表示成功与否，业务数据用引用参数带出，错误信息统一走一个错误字符串指针。这样调用方被迫处理失败分支，日志里也能打出真实的系统错误：

bool readLines(const QString &path, QStringList &out, QString *errorMsg = nullptr);

errorMsg里的内容来自QFile::errorString()，它会给出“No such file or directory”“Permission denied”这类具体信息，比笼统的“读取失败”有用得多。加上文件路径一起记进日志，排查效率完全不是一个级别。

4.2 逐行读大文件：带进度和可中断的版本

处理大文件时，我的循环里一定会放两个东西：进度回调和中断标志。前者是为了让 UI 能显示进度条，不至于让用户以为程序死了；后者是为了让用户能点取消。这两个需求在小文件上看不出来，在几百兆的文件上是刚需。

// 返回 false 表示被中断 bool processLargeFile(const QString &path, const std::function<bool(qint64, qint64)> &onProgress, QString *errorMsg) { QFile f(path); if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) { if (errorMsg) *errorMsg = f.errorString(); return false; } const qint64 total = f.size(); qint64 done = 0; qint64 lastReport = 0; QByteArray line; while (!f.atEnd()) { line = f.readLine(); done += line.size(); // 每 512KB 报一次，避免信号风暴 if (done - lastReport >= 512 * 1024) { lastReport = done; if (!onProgress(done, total)) return false; // 用户取消 } if (line.endsWith('\n')) line.chop(1); if (line.endsWith('\r')) line.chop(1); // 这里的 line 是原始字节，按需解码后再做业务 } onProgress(total, total); return true; }

两个细节值得展开。进度上报要做节流，按字节累积到 512KB 才报一次，而不是每行都发一个信号。逐行发信号的话，一个三百万行的文件会发三百万次跨线程信号，光是事件循环排队就能让界面卡成幻灯片。中断用返回值而不是异常或标志位，是因为调用方看到false就必须处理，而标志位很容易被人忘了检查。

读循环里那个字节剥换行的操作，和前面 2.1 讲的顺序一致：先\n后\r。如果你的文件是从网络下载或者跨系统传输来的，行尾可能是\r\n、\n、\r三种中的任意一种，上面这段代码三种都能处理。

4.3 原子写入：QSaveFile 的正确用法

写文件最怕的是什么？写到一半程序崩了、磁盘满了、用户拔了 U 盘，结果原文件被截断成半截，配置全丢。这个问题在 Qt 里有现成的解：QSaveFile。

它的原理不复杂：先写一个同目录下的临时文件，全部写成功后调用commit()，由系统执行一次原子替换。这样任何中途失败都不会污染原文件。用法上只有一个关键点容易错：QTextStream或QDataStream包在QSaveFile外面时，必须先让流写入完成再 commit，否则流缓冲区里没落盘的数据就丢了。

bool writeTextFile(const QString &path, const QStringList &lines, QString *errorMsg) { QSaveFile sf(path); if (!sf.open(QIODevice::WriteOnly | QIODevice::Text)) { if (errorMsg) *errorMsg = sf.errorString(); return false; } { QTextStream ts(&sf); ts.setEncoding(QStringConverter::Utf8); // Qt 6；Qt 5 用 setCodec("UTF-8") ts.setLocale(QLocale::c()); // 防止数字被本地化 for (const QString &l : lines) { ts << l << '\n'; } ts.flush(); } // 这里 ts 析构，缓冲区彻底落盘 if (!sf.commit()) { if (errorMsg) *errorMsg = sf.errorString(); return false; } return true; }

用大括号把QTextStream的生命周期框起来，是为了让它在commit()之前析构。这是个看着有点刻意的写法，但它能避免一类非常隐蔽的问题：流对象还活着的时候数据可能还在缓冲区里，这时commit()拿到的临时文件是不完整的。我早期就因为这个丢过一次配置，后来这个花括号就成了固定动作。

注意：QSaveFile要求目标路径所在的目录可写，因为临时文件要创建在同一个目录下。如果目录本身不可写，open()就会失败。另外它默认不会自动创建不存在的目录，写之前该建目录就得建。

补充一个参数：QSaveFile::setDirectWriteFallback(true)可以让它在无法创建临时文件时退化成直接写。这个选项在正常桌面环境下我建议保持默认的关闭状态，因为它会牺牲原子性；只有在某些受限文件系统（比如某些网络挂载）上临时文件创建总失败时，才打开它作为兜底。

4.4 追加日志与实时刷新

日志这种场景和配置文件正好相反：追加、频繁、要求实时可见。QIODevice::Append打开文件，写完了必须flush()，因为操作系统有缓冲，不刷的话别人tail你的日志会看到内容延迟几分钟才出现。

bool appendLog(const QString &path, const QString &text) { QFile f(path); if (!f.open(QIODevice::WriteOnly | QIODevice::Append | QIODevice::Text)) return false; f.write(QDateTime::currentDateTime() .toString("yyyy-MM-dd HH:mm:ss.zzz ").toUtf8()); f.write(text.toUtf8()); f.write("\n"); f.flush(); // 关键，日志必须刷 return true; }

这里我直接用QFile::write拼字节，没有用QTextStream。原因是日志追求的是低开销和高可预测性，用流对象每次都要构造析构，而QDateTime::toString返回的QString转QByteArray已经很直接了。频率高的日志（比如每帧都写）还要再加一层：内存里先攒几百毫秒的缓冲，批量落盘，否则磁盘 IO 会成为瓶颈，尤其是在机械硬盘或者网络盘上。

还有一个细节：多线程同时写日志时，QFile对象不是线程安全的。共享一个QFile写日志，轻则内容交错，重则崩溃。标准做法是加锁，或者每个线程持有自己的文件句柄，或者干脆只在一个专门的日志线程里写，其他线程通过队列投递消息。

4.5 工程配置：qmake 和 CMake 的最小写法

这段东西本来不值得写，但新手在编码相关的模块上经常卡在链接错误上，所以还是列一下。Qt 6 的 CMake 最小配置：

cmake_minimum_required(VERSION 3.16) project(TextIoDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) find_package(Qt6 REQUIRED COMPONENTS Core) # 需要 Qt 5 兼容的 QTextCodec 时再加上 Core5Compat # find_package(Qt6 REQUIRED COMPONENTS Core5Compat) add_executable(TextIoDemo main.cpp) target_link_libraries(TextIoDemo PRIVATE Qt6::Core)

如果你走 Qt5Compat 那条路，target_link_libraries里要加上Qt6::Core5Compat，头文件是#include <QTextCodec>。用 qmake 的老项目对应写QT += core，需要兼容模块时写QT += core core5compat。

用QStringDecoder、QStringEncoder、QStringConverter这些只需要Qt6::Core，不用额外模块，这也是它比QTextCodec轻的地方。代价就是编码支持范围变窄，前面 3.2 已经聊过了。

5. 性能、线程与路径的实战细节

5.1 读取方式对比：什么时候该放弃逐行

我把常见的几种读取方式在我的开发机上跑过对比，文件是一个约 200MB、三百万行的 CSV。下面的数字是量级参考，不是标准基准，你的机器和环境不同会差不少，但相对关系是稳定的。

readAll在时间上确实最快，因为只有一次系统调用和一次内存分配，字符串切分也是顺序访问，缓存友好。但它的内存放大非常恐怖：200MB 的QByteArray变成约 300 万个QString对象，每个QString至少有对象头和独立的堆分配，加起来轻松到 1.5GB 以上。所以我的判断标准很简单：文件小于可用内存的十分之一，用readAll；否则一律逐行或分块。

分块读取的块大小我一般取 64KB。太小会导致系统调用次数暴增，太大对内存和缓存都不友好。64KB 是磁盘页大小和 CPU 缓存行之间的一个常见折中值，实践中比 4KB 快，比 1MB 稳定。

内存映射是个被低估的方案，特别适合“只读、需要按偏移量跳转”的场景，比如在超大日志里按时间戳定位。用QFile::map(0, f.size())拿到裸指针，然后用QByteArrayView包一下直接扫描。要注意两点：32 位程序的地址空间有限，映射超过 1.5GB 的文件大概率失败，必须做返回值判断；映射之后文件不能被其他程序截断或删除，否则访问映射区会直接崩溃，处理不可信来源的文件时要格外小心。

5.2 把读写放到工作线程里

GUI 程序里最忌讳的就是在主线程里同步读一个大文件。哪怕只是一秒钟，界面也会完全冻结，用户会以为程序卡死了。正确做法是把读写放到工作线程，通过信号把进度和结果传回界面。

有两个技术点必须搞清楚。第一，QFile对象要在哪个线程创建就在哪个线程使用，不能在一个线程创建然后丢给另一个线程操作。这不是“建议”而是必须遵守的约束，跨线程用同一个QFile会出现难以复现的数据错乱。第二，同一个文件不要用多个QFile对象同时写，两个句柄的写入位置和缓冲互不感知，内容会互相覆盖。

用QThread+moveToThread的经典写法：

class FileWorker : public QObject { Q_OBJECT public slots: void doRead(const QString &path) { QStringList lines; QString err; const bool ok = readLines(path, lines, &err); if (ok) emit finished(lines); else emit failed(err); } signals: void finished(const QStringList &lines); void failed(const QString &message); }; // 调用侧 auto *thread = new QThread(this); auto *worker = new FileWorker; worker->moveToThread(thread); connect(thread, &QThread::started, worker, [worker, path]{ worker->doRead(path); }); connect(worker, &FileWorker::finished, this, &MainWindow::onFileLoaded); connect(worker, &FileWorker::failed, this, &MainWindow::onFileFailed); thread->start();

注意信号传参用了QStringList而不是指针，跨线程信号会自动做队列连接，参数会被拷贝一份到接收线程。如果文件很大，拷贝本身也是一笔开销，这时候更合适的做法是只传结果统计，数据留在工作线程处理完再传回精简结果。我处理百万行 CSV 时的做法就是：工作线程直接解析并聚合成统计结果，只把最终的小结构体传回主线程。

还有一个常见需求是监控文件变化，比如配置文件被外部编辑后自动重新加载。用QFileSystemWatcher就能实现，但有个坑：很多编辑器保存文件的方式是“写临时文件再重命名覆盖”，这会导致监听失效，因为原始的 inode 已经不存在了。处理办法是收到fileChanged之后重新addPath，并且在处理里加一个短延时，避免在编辑器还没写完时就去读。

5.3 路径、权限和跨平台差异

路径问题我踩过的坑排前三。第一条是绝对不要把QString路径转成const char*再传给QFile::open。QFile接受QString的路径是完整的 Unicode 支持，转成char*之后会走本地 8 位编码转换，中文路径在 Windows 上就会打不开。这个问题在老代码里特别多，因为早期有人习惯写f.open(path.toLocal8Bit())。

第二条是路径分隔符。Qt 内部统一用/，Windows 也认，所以写"config/app.ini"在所有平台都能跑。只有在需要把路径展示给用户时才用QDir::toNativeSeparators()转成本地风格。反过来，用户从对话框里拿到的路径可能带反斜杠，QFile也能处理，不用手动替换。

第三条是写权限。QFile::open失败后必须看errorString()，因为不同原因的表现一样，但解决方式完全不同：文件不存在要建文件或换路径，目录不存在要建目录，权限不足要换目录或者提示用户，被占用则是另一回事（Windows 上文件被其他程序独占打开时会失败）。我在写关键配置时会给用户一个明确的提示弹窗，而不是只往日志里写一行，因为用户看不到日志。

最后是写到哪里的问题。程序的配置文件绝对不能写在自己的安装目录下，因为现代系统的程序目录通常不可写。正确做法是用QStandardPaths：

const QString dir = QStandardPaths::writableLocation( QStandardPaths::AppConfigLocation); QDir().mkpath(dir); // 目录可能不存在 const QString path = dir + "/settings.json";

AppConfigLocation在不同平台会落到各自规范的目录（Windows 的用户 AppData、Linux 的~/.config/应用名、macOS 的~/Library/Preferences/应用名），系统会自动带上应用名子目录。这个调用比手拼路径靠谱得多，尤其是应用名带中文或者空格的时候。

6. 常见问题速查与踩坑记录

6.1 问题速查表

下面这些是我在实际项目里被问过、也被自己坑过的问题，按现象归类，方便按症状查。

表格能覆盖大部分高频问题，但有几类问题光看现象很难定位，必须结合日志和环境信息。所以我在模块里统一了错误上报：所有失败路径都带上文件路径、系统错误串、以及操作类型，日志里一搜就能定位。

6.2 三个我真实踩过的坑

第一个坑：默认编码的假定害了我一个下午。项目里的配置文件一直是自己写的，UTF-8，跑了一年多没问题。直到有测试同学用手动编辑的方式改了一版配置，用的是某个国产编辑器，保存成了 GBK。程序读的时候按 UTF-8 解，键值全变成乱码，但因为是 key 匹配失败，表现是“配置不生效”，完全没有报错。我查了半天代码逻辑才想到去看文件的十六进制。从那以后，我在所有面向用户的文本文件读取里都加了编码探测，探测结果还会写进日志。这个日志后来帮我定位了好几次类似问题。

第二个坑：以为是性能问题，其实是信号风暴。有个导出功能，在开发机上导 5 万行只要两秒，到了用户的机器上导 20 万行要三分钟。一开始我以为是磁盘慢，加了各种缓冲优化没什么效果。后来用性能分析工具一看，时间全花在事件循环上——我每处理一行就发一个进度信号，20 万行就是 20 万次跨线程排队。改成按字节节流上报之后，同样的文件一秒多就跑完了。这个教训让我形成了习惯：任何在循环里发信号的地方，都要先问一句“这个循环最多会跑多少次”。

第三个坑：QSaveFile救了我一次，也差点坑了我一次。原子写入确实好用，但有一次在 Linux 上写配置总是失败，commit()返回 false 而errorString()只说写入失败。查了半天发现目标目录挂在一个特殊文件系统上，不支持同目录的临时文件创建。这种情况下QSaveFile的兜底选项setDirectWriteFallback(true)就能起作用，退化成直接写。我最后的选择是在这个特定目录下开兜底，其他目录保持原子性。这类问题的通用经验是：原子写入的失败往往不是权限问题，而是文件系统的能力限制，换目录或者开兜底，比一直查权限有用。

6.3 关于测试的一点补充建议

文本读写这块的测试，很多人只测“正常路径”，我觉得价值不大。真正值得写测试的是边界：空文件、只有一行且没有换行符、全是空行、超过 2GB 的文件（如果业务上可能遇到，至少要测 64 位下的偏移计算）、带 BOM 的文件、GBK 文件、混合换行符的文件、只读文件、目录不存在的路径。这几类我都在不同项目里遇到过真实案例，写一个覆盖它们的测试函数，成本不到半小时，能省掉后面几天的排查时间。

测试数据建议放在代码仓库里作为固定 fixture，而不是每次动态生成，因为动态生成的测试数据在不同环境下可能不一样，尤其是涉及 locale 的时候。另外要特别注意测试环境的 locale 设置，一个在Clocale 下通过的测试，在中文 locale 的机器上可能就失败——前面说的小数点问题就是这么冒出来的。

7. 一点个人体会和后续可扩展的方向

写 Qt 文本文件读写这几年，我最大的体会是：这个领域的问题几乎都不是 API 用错，而是场景没分清楚。把配置文件、数据文件、用户文本、日志这四类分开对待之后，代码会自然地变得清晰，选型也会变得没有争议。反过来说，任何试图写一个“万能读写函数”覆盖所有场景的尝试，最后都会变成一个满是参数和分支的怪物，维护成本远超收益。

如果这套东西在你的项目里稳定下来了，有两个方向可以继续扩展。一个是把编码探测抽成一个独立的小组件，缓存探测结果，避免每次读同一个文件都重新探测；另一个是给大文件处理加上断点续读能力，把已处理的字节偏移量记进一个伴随文件，程序重启后从上次位置继续。这两个扩展都不复杂，但在处理日志分析和数据导入这类场景时非常实用。

最后分享一个小习惯：我会在开发期的读写函数里加一个环境变量控制的调试开关，打开之后会把文件路径、探测到的编码、总字节数、处理行数和耗时打进日志。这个开关在发布版里默认关掉，代码只有几行，但它在我定位“用户说导入很慢”“用户说文件读出来少了几行”这类问题时，几乎是每次都能省下至少一小时。