AwesomeQt 教程

Appearance

现代Qt开发教程（进阶篇）1.8——文件IO进阶：序列化与文件监控 ​

1. 前言 / 会读写文件只是起点 ​

说实话，入门篇里我们聊了 QFile 读写、QTextStream 文本流、QDir 目录操作这些基本功，日常写个小工具已经够用了。但真正到了正经项目里，光会读写文本文件是远远不够的。你需要把一堆自定义结构体存到磁盘上再读回来——这叫序列化；你需要监控某个配置文件被外部修改了然后自动重载——这叫文件监控；你需要在写入文件时保证哪怕突然断电也不会损坏数据——这叫原子写入；你还需要处理几个 GB 的大文件而内存只有几百 MB——这时候内存映射文件就是救命稻草。这些进阶能力，就是我们今天要啃的骨头。

笔者之前做一个数据分析工具的时候踩了一堆让人血压拉满的坑：用 QDataStream 存了一堆数据，Qt 升级之后格式变了，老数据全读不出来了；用 QFileSystemWatcher 监控日志目录，Windows 上好好的到了 Linux 上疯狂触发重复信号；写文件写一半程序崩了，配置文件变成零字节，下次启动直接读了个寂寞。这些坑，一个比一个阴险，我们今天一个一个填上。

2. 环境说明 ​

本篇基于 Qt 6.5+、CMake 3.26+、C++17 标准。所有文件 IO 相关类都在 QtCore 模块中，不需要额外链接其他模块。QDataStream 的版本策略在 Qt 5 到 Qt 6 的迁移中发生了一些变化，如果你的项目还停留在 Qt 5，版本兼容的处理方式有所不同但核心思路相通。

3. 核心概念讲解 ​

3.1 QDataStream 二进制序列化——版本兼容策略 ​

入门篇我们演示了 QDataStream 的基本读写，但没展开讨论一个极其关键的问题：你写入的数据格式和你读取的数据格式必须完全匹配，不只是字段顺序，还包括 Qt 内部的序列化编码方式。而 Qt 的序列化编码在不同大版本之间是会变的——比如 Qt 5.6 中 QString 的序列化方式和 Qt 5.15 不一样，Qt 6.x 又有新的调整。如果你的程序用 Qt 5.15 写了数据，升级到 Qt 6 之后用默认设置去读，大概率读到一堆乱码。

解决方案就是 QDataStream::setVersion()。这个方法指定序列化时使用的二进制协议版本，确保读写两端使用相同的编码规则。

cpp
// 写入端
QFile file("data.bin");
file.open(QIODevice::WriteOnly);
QDataStream out(&file);
out.setVersion(QDataStream::Qt_6_0);  // 锁定版本
out << QString("hello") << 42 << 3.14;

// 读取端（即使 Qt 版本升级，只要 setVersion 相同就能正确读取）
QFile file("data.bin");
file.open(QIODevice::ReadOnly);
QDataStream in(&file);
in.setVersion(QDataStream::Qt_6_0);  // 必须与写入时相同
QString s;
int i;
double d;
in >> s >> i >> d;

工程实践中的最佳做法是：在程序的第一版就确定 QDataStream 版本号，然后用常量定义它。后续版本即使 Qt 升级了，只要 setVersion 不变，旧数据永远能正确读取。如果确实需要变更数据格式，可以新增一个文件头标识来区分新旧格式。

更进一步，建议在文件开头写入一个自定义的魔数和版本号，这样即使文件被误用其他程序打开，也能在读取前检测出来。

3.2 QFileSystemWatcher——文件监控的跨平台陷阱 ​

QFileSystemWatcher 提供了跨平台的文件和目录变更监控能力。它的 API 非常简单：addPath() 添加监控路径，fileChanged() 和 directoryChanged() 信号通知变更。但这个看似简单的接口背后藏着大量的跨平台差异。

在 Linux 上，QFileSystemWatcher 底层使用 inotify。inotify 的事件粒度很细，一个文件的修改可能触发多次 fileChanged 信号（写入数据是一次，更新文件元数据是一次，关闭文件又是一次）。如果你在槽函数里直接重新读取文件内容，可能会读到写入了一半的不完整数据。

在 Windows 上，底层使用 ReadDirectoryChangesW。Windows 对文件修改通常只触发一次通知，但如果修改是由某些编辑器（比如 Vim）完成的，Vim 可能采用「写入新文件 + 删除旧文件 + 重命名」的策略，这会导致 QFileSystemWatcher 认为旧文件被删除了，停止监控——然后你再修改文件就收不到通知了。

在 macOS 上，底层使用 kqueue。kqueue 的行为和 inotify 类似，但对某些文件系统（特别是网络挂载的卷）可能不触发通知。

解决方案是：收到 fileChanged 信号后，不要立即处理，而是启动一个短延迟定时器（比如 300ms），把同一文件的多次通知合并为一次处理。处理完后重新调用 addPath() 确保监控没有被取消。

3.3 原子写入——断电安全的数据保存 ​

当你用普通的 QFile 写入文件时，如果在写入过程中程序崩溃或断电，文件可能处于不一致的状态——旧数据已经被截断但新数据还没写完。对于配置文件来说，这意味着下次启动时读到的是一个损坏的文件，程序无法正常工作。

原子写入的核心思路是：不直接写入目标文件，而是先写入一个临时文件，写入完成后用 rename 操作替换目标文件。rename 在 POSIX 系统上是原子的——要么成功替换，要么保持原样，不存在中间状态。

cpp
bool atomic_write(const QString& targetPath, const QByteArray& data)
{
    QString tempPath = targetPath + ".tmp";

    // 第一步：写入临时文件
    QFile tempFile(tempPath);
    if (!tempFile.open(QIODevice::WriteOnly)) {
        return false;
    }
    if (tempFile.write(data) != data.size()) {
        tempFile.remove();
        return false;
    }
    tempFile.close();

    // 第二步：确保数据刷到磁盘
    // fsync 保证即使断电，临时文件的数据也不会丢失
    #ifdef Q_OS_UNIX
    int fd = open(tempPath.toUtf8().constData(), O_RDONLY);
    if (fd >= 0) {
        fsync(fd);
        close(fd);
    }
    #endif

    // 第三步：原子替换
    QFile::remove(targetPath);
    return QFile::rename(tempPath, targetPath);
}

现在有一道思考题。上面的代码在 Windows 上有什么问题？提示：Windows 上如果目标文件正在被其他进程使用，QFile::remove() 会失败。如何改进？

答案是：Windows 上需要用 MoveFileEx 配合 MOVEFILE_REPLACE_EXISTING 标志来原子替换文件。Qt 6 的 QFile::rename() 在 Windows 上已经使用了这个标志，所以如果你用的是 Qt 6，直接用 QFile::rename() 即可。但 Qt 5 的行为不同，需要手动处理。

3.4 内存映射文件——大文件处理的利器 ​

当你需要处理几个 GB 的大文件时，逐行读取可能太慢，一次性 readAll 内存又撑不住。这时候内存映射文件（mmap）就是最佳选择。QFile 提供了 map() 和 unmap() 方法，直接把文件内容映射到进程的虚拟地址空间中。映射后你就可以像访问内存数组一样访问文件内容，操作系统负责按需加载页面，不需要你手动管理缓冲区。

cpp
QFile file("large_data.bin");
file.open(QIODevice::ReadOnly);

// 映射前 1GB（或者全部）
uchar* data = file.map(0, qMin(file.size(), qint64(1024 * 1024 * 1024)));
if (data) {
    // 直接用指针访问文件内容，零拷贝
    // 操作系统按需加载页面，不需要手动 read()
    quint32 value = *reinterpret_cast<quint32*>(data + offset);

    file.unmap(data);
}

内存映射的限制是：32 位进程的地址空间只有 2-3 GB，无法映射超过这个大小的文件。64 位进程没有这个限制，但映射过大的文件可能导致虚拟内存耗尽。工程实践中的建议是：按区域映射（每次映射几百 MB），处理完后 unmap 再映射下一个区域。

4. 踩坑预防 ​

第一个坑是 QDataStream 版本号不一致导致数据损坏。前面详细讲过了，但后果必须强调——不是读到乱码那么简单，而是可能读到「看起来正常但实际是错误的数据」。比如一个 double 值的字节序被错误解析，你可能得到一个「合理」的数值但完全不正确。解决方案是在文件头写入魔数和版本号，读取时先校验再解析。

第二个坑是 QFileSystemWatcher 在某些编辑器下丢失监控。前面也讲过了。后果是配置文件被修改了但程序没有收到通知，用户以为配置已生效但实际还是旧值。解决方案是收到 fileChanged 后总是重新 addPath，并用延迟合并策略避免处理不完整的写入。

第三个坑是内存映射文件忘记 unmap 导致文件被锁定。在 Windows 上，被映射的文件无法被其他进程删除或修改。如果你的程序映射了一个文件但忘记 unmap，这个文件就会一直被锁定，直到程序退出。后果是用户无法删除或替换该文件，程序也无法再次写入同一个文件。解决方案是用 RAII 模式管理映射——构造时 map，析构时 unmap，或者使用 std::unique_ptr 配合自定义 deleter。

5. 练习项目 ​

练习项目：断电安全的配置管理器。我们要实现一个配置文件管理类，支持原子写入、版本化序列化和文件变更监控。

具体要求是：ConfigManager 类提供 load() 和 save() 方法，内部使用 QDataStream 序列化，文件头包含魔数和版本号。save() 使用原子写入策略（写临时文件 + rename）。启动 QFileSystemWatcher 监控配置文件，外部修改时自动重载并用信号通知调用方。完成标准是：写入过程中 kill 程序后配置文件不损坏、Qt 升级后旧配置文件仍可正确读取、外部编辑器修改配置后程序自动检测到变更。

提示几个关键点：魔数用自定义的 4 字节标记（比如 "ACFG"），QDataStream 版本用常量定义，原子写入用临时文件 + rename，文件监控用延迟合并策略。

6. 官方文档参考链接 ​

Qt 文档 · QDataStream -- 二进制序列化类参考

Qt 文档 · QFileSystemWatcher -- 文件系统监控

Qt 文档 · QFile -- 文件操作类（含 map/unmap）

到这里，文件 IO 的进阶知识就全部拆完了。版本化序列化、跨平台文件监控、原子写入、内存映射——这些是处理工程级文件操作的必备技能。下一篇我们来看 JSON 和 XML 的进阶处理：流式解析大文件和 CBOR 二进制格式。

基于 VitePress 构建

Copyright 2025-2026 Charliechen