QC++ / Qt 学习之路

进程通信与系统级功能

QProcess、IPC、托盘、国际化与资源系统

进阶第 34 / 48 章第四篇 · Qt 进阶

#QProcess:启动并控制外部程序

QProcess 继承自 QIODevice,它把"另一个进程"抽象成一个可读写的设备。启动外部程序是桌面应用的常见需求:调用 ffmpeg 转码、打开系统文件管理器、运行脚本。

核心 API 有三个:

函数行为适用
start(program, args)异步启动,立即返回推荐,不阻塞 UI
startDetached()启动后脱离,父进程退出子进程也不受影响打开独立程序
execute()同步阻塞等待结束仅命令行工具/测试
C++
// ===== 文件 1:runner.h =====
#pragma once
#include <QObject>
#include <QProcess>

class Runner : public QObject
{
    Q_OBJECT
public:
    explicit Runner(QObject *parent = nullptr);

    void run(const QString &program, const QStringList &args);

signals:
    void output(const QString &line);
    void finished(int exitCode, bool ok);

private:
    QProcess m_proc;
};

// ===== 文件 2:runner.cpp =====
#include "runner.h"
#include <QProcessEnvironment>
#include <QDir>
#include <QDebug>

Runner::Runner(QObject *parent) : QObject(parent)
{
    // 标准输出:有数据就触发,注意不保证按整行到达
    connect(&m_proc, &QProcess::readyReadStandardOutput, this, [this] {
        m_proc.setReadChannel(QProcess::StandardOutput);
        while (m_proc.canReadLine()) {
            emit output(QString::fromUtf8(m_proc.readLine()).trimmed());
        }
    });

    connect(&m_proc, &QProcess::readyReadStandardError, this, [this] {
        m_proc.setReadChannel(QProcess::StandardError);
        while (m_proc.canReadLine()) {
            emit output("[err] " + QString::fromUtf8(m_proc.readLine()).trimmed());
        }
    });

    connect(&m_proc, &QProcess::finished,
            this, [this](int code, QProcess::ExitStatus status) {
        emit finished(code, status == QProcess::NormalExit && code == 0);
    });

    connect(&m_proc, &QProcess::errorOccurred,
            this, [](QProcess::ProcessError err) {
        qWarning() << "进程错误:" << err;
    });
}

void Runner::run(const QString &program, const QStringList &args)
{
    m_proc.setWorkingDirectory(QDir::homePath());        // 设置工作目录

    // 追加环境变量(不清空原有环境)
    QProcessEnvironment env = QProcessEnvironment::systemEnvironment();
    env.insert("MY_APP_MODE", "batch");
    m_proc.setProcessEnvironment(env);

    m_proc.start(program, args);                         // 异步,立即返回
}

三个实战要点:

  1. 参数用 QStringList 传,不要拼字符串。拼出来的命令行遇到带空格的路径(`C:\Program Files\...)就会解析错误。start() 直接调用 execvp` 系列,不经 shell,天然安全。
  2. 输出要边读边处理。如果子进程输出大量数据而你从不读,管道缓冲区满了会阻塞子进程,形成死锁。所以一定要连 readyReadStandardOutput。
  3. errorOccurred 与 finished 不同:前者是"进程根本没跑起来"(程序不存在、权限不足),后者是"跑完退出了"。两者都要处理。

#本地套接字 QLocalServer / QLocalSocket

QLocalSocket 用于同一台机器上的进程间通信。它走命名管道(Windows)或 Unix domain socket(Linux/macOS),比 TCP 回环更快,且可用文件系统权限控制访问。

典型用途是单实例应用:第二个实例启动时,把命令行参数发给已运行的实例,然后自己退出。

C++
// ===== 文件 1:singleinstance.h =====
#pragma once
#include <QObject>
#include <QLocalServer>
#include <QLocalSocket>
#include <QString>

class SingleInstance : public QObject
{
    Q_OBJECT
public:
    explicit SingleInstance(const QString &serverName, QObject *parent = nullptr);

    bool tryRunPrimary();                    // 尝试作为主实例启动
    bool notifyPrimary(const QString &msg);  // 作为从实例通知主实例

signals:
    void messageReceived(const QString &msg);

private:
    QString      m_name;
    QLocalServer m_server;
};

// ===== 文件 2:singleinstance.cpp =====
#include "singleinstance.h"
#include <QDebug>

SingleInstance::SingleInstance(const QString &serverName, QObject *parent)
    : QObject(parent), m_name(serverName)
{
    connect(&m_server, &QLocalServer::newConnection, this, [this] {
        QLocalSocket *client = m_server.nextPendingConnection();
        connect(client, &QLocalSocket::readyRead, this, [this, client] {
            emit messageReceived(QString::fromUtf8(client->readAll()));
        });
        connect(client, &QLocalSocket::disconnected,
                client, &QLocalSocket::deleteLater);
    });
}

bool SingleInstance::tryRunPrimary()
{
    // 管道被占用说明已有实例在跑
    if (!m_server.listen(m_name)) {
        // Unix 下崩溃残留的 socket 文件会导致假占用,清理后重试
        QLocalServer::removeServer(m_name);
        return m_server.listen(m_name);
    }
    return true;
}

bool SingleInstance::notifyPrimary(const QString &msg)
{
    QLocalSocket sock;
    sock.connectToServer(m_name);
    if (!sock.waitForConnected(1000)) {
        return false;
    }
    sock.write(msg.toUtf8());
    sock.flush();
    sock.waitForBytesWritten(1000);
    sock.disconnectFromServer();
    return true;
}

// ===== 文件 3:main.cpp =====
#include <QApplication>
#include <QDebug>
#include "singleinstance.h"

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QApplication::setApplicationName("MyApp");

    SingleInstance guard("MyApp_SingleInstance_Key");
    if (!guard.tryRunPrimary()) {
        // 已有实例:把参数转给它,自己退出
        guard.notifyPrimary(app.arguments().mid(1).join('\n'));
        qInfo() << "已有实例在运行,参数已转发。";
        return 0;
    }

    connect(&guard, &SingleInstance::messageReceived,
            &app, [](const QString &msg) {
        qDebug() << "收到来自新实例的参数:" << msg;
    });

    return app.exec();   // 正常启动主窗口
}

QLocalServer::removeServer() 是 Unix 下的必备防御:程序崩溃时 socket 文件不会自动清理,下次启动会误判为"已运行"。

#共享内存与 D-Bus

#QSharedMemory

QSharedMemory 提供跨进程的内存共享,适合大数据、低延迟场景,比如图像采集进程与显示进程之间传递帧。

但它有两个硬约束:不保证访问控制(需自己用 QSystemSemaphore 同步);不能存指针——共享内存在不同进程映射到不同虚拟地址,存进去的指针在另一个进程是野指针,只能存 POD 数据或相对偏移。

#QDBus 简介

QDBus 是 Qt 对 D-Bus 的封装,仅在 Unix/Linux 可用(Windows 无原生 D-Bus)。D-Bus 分两种总线:Session Bus(每个登录会话一条,用于桌面应用互相通信)和 System Bus(系统级,用于网络管理、电源管理等系统服务)。

调用远端方法的写法很固定:用 QDBusInterface 指定服务名、对象路径、接口名与总线,然后 call();返回值用 QDBusReply<T> 包装,务必先 isValid() 再取值。下面的示例把这两部分放在一起:

C++
// ===== 文件 1:shmframe.cpp —— 共享内存传帧 =====
#include <QSharedMemory>
#include <QSystemSemaphore>
#include <QSystemSemaphore>
#include <QBuffer>
#include <QDataStream>
#include <QImage>
#include <QDebug>

// 写入端:把一张图放进共享内存
bool writeFrame(const QString &key, const QImage &img)
{
    QSharedMemory  shm(key);
    QSystemSemaphore sem(key + "_sem", 1);      // 初始资源数 1,充当互斥锁

    QBuffer buffer;
    buffer.open(QIODevice::WriteOnly);
    QDataStream out(&buffer);
    out << img;                                  // QImage 支持 QDataStream 序列化
    const QByteArray bytes = buffer.data();

    sem.acquire();                               // 加锁
    bool ok = false;
    if (shm.create(bytes.size())) {
        ok = true;
    } else if (shm.error() == QSharedMemory::AlreadyExists) {
        if (shm.attach()) {
            if (shm.size() >= bytes.size()) {
                ok = true;                       // 已存在且够大,复用
            } else {
                shm.detach();                    // 尺寸不足:重建
                ok = shm.create(bytes.size());
            }
        }
    }
    if (ok && shm.isAttached()) {
        shm.lock();
        std::memcpy(shm.data(), bytes.constData(),
                    static_cast<size_t>(bytes.size()));
        shm.unlock();
    }
    sem.release();                               // 解锁
    return ok;
}

// 读取端
QImage readFrame(const QString &key)
{
    QSharedMemory shm(key);
    if (!shm.attach(QSharedMemory::ReadOnly)) {
        return {};
    }

    QBuffer buffer;
    shm.lock();
    buffer.setData(static_cast<const char *>(shm.constData()), shm.size());
    shm.unlock();
    shm.detach();

    buffer.open(QIODevice::ReadOnly);
    QDataStream in(&buffer);
    QImage img;
    in >> img;
    return img;
}

// ===== 文件 2:dbushostname.cpp —— D-Bus 方法调用 =====
#include <QDBusConnection>
#include <QDBusInterface>
#include <QDBusReply>
#include <QDebug>

// 例:通过 D-Bus 查询系统主机名(systemd-hostnamed)
QString queryHostname()
{
    QDBusInterface iface(
        "org.freedesktop.hostname1",          // 服务名
        "/org/freedesktop/hostname1",         // 对象路径
        "org.freedesktop.hostname1",          // 接口名
        QDBusConnection::systemBus());

    if (!iface.isValid()) {
        qWarning() << "D-Bus 服务不可用:" << iface.lastError().message();
        return {};
    }

    QDBusReply<QString> reply =
        iface.call("Get", "org.freedesktop.hostname1", "Hostname");
    if (!reply.isValid()) {
        qWarning() << "调用失败:" << reply.error().message();
        return {};
    }
    return reply.value();
}

注意 QSharedMemory 在 Unix 上的生命周期与内核绑定,进程退出后仍然存活;Windows 上最后一个进程退出即销毁。因此关键数据要有独立清理逻辑,不能依赖进程退出。使用 D-Bus 时还需在 CMake 中链接 Qt6::DBus,并记得用 if(UNIX AND NOT APPLE) 条件包裹,避免破坏 Windows 构建。

#IPC 方案怎么选

需求方案
单实例检测 + 传参QLocalServer
大块数据共享QSharedMemory + QSystemSemaphore
跨机器通信QTcpSocket
Linux 桌面环境集成QDBus
简单触发外部程序QProcess::startDetached()

#系统交互:托盘与剪贴板

托盘图标是后台类应用的标配,剪贴板则是数据交换的快捷通道。两者都属于 QGuiApplication/QApplication 提供的系统级能力。

C++
#include <QApplication>
#include <QSystemTrayIcon>
#include <QClipboard>
#include <QMimeData>
#include <QMenu>
#include <QAction>
#include <QMainWindow>
#include <QCloseEvent>
#include <QIcon>
#include <QDebug>

class MainWindow : public QMainWindow
{
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr) : QMainWindow(parent)
    {
        setWindowTitle("托盘示例");
        setWindowIcon(QIcon(":/icons/app.svg"));

        // 托盘需要可用性和图标,缺失时给出提示
        if (!QSystemTrayIcon::isSystemTrayAvailable()) {
            qWarning() << "当前环境不支持系统托盘";
            return;
        }

        auto *showAct = new QAction("显示主窗口", this);
        auto *quitAct = new QAction("退出", this);
        connect(showAct, &QAction::triggered, this, [this] {
            show();
            raise();
            activateWindow();
        });
        connect(quitAct, &QAction::triggered, qApp, &QApplication::quit);

        auto *menu = new QMenu(this);
        menu->addAction(showAct);
        menu->addSeparator();
        menu->addAction(quitAct);

        m_tray = new QSystemTrayIcon(windowIcon(), this);
        m_tray->setToolTip("托盘示例程序");
        m_tray->setContextMenu(menu);
        connect(m_tray, &QSystemTrayIcon::activated,
                this, [this](QSystemTrayIcon::ActivationReason reason) {
            if (reason == QSystemTrayIcon::DoubleClick
             || reason == QSystemTrayIcon::Trigger) {
                setVisible(!isVisible());
            }
        });
        m_tray->show();
    }

protected:
    void closeEvent(QCloseEvent *e) override
    {
        // 关闭时最小化到托盘而非退出
        if (m_tray && m_tray->isVisible()) {
            hide();
            e->ignore();
            m_tray->showMessage("已最小化到托盘", "双击图标可重新打开窗口",
                               QSystemTrayIcon::Information, 2000);
        } else {
            QMainWindow::closeEvent(e);
        }
    }

private:
    QSystemTrayIcon *m_tray = nullptr;
};

// 剪贴板:文本与富数据
void clipboardDemo()
{
    QClipboard *cb = QApplication::clipboard();

    cb->setText("要复制的文本");                      // 写入
    const QString text = cb->text();                 // 读取

    auto *data = new QMimeData;
    data->setImageData(QImage(":/icons/logo.png"));
    data->setData("application/x-myapp-meta", "custom payload");
    cb->setMimeData(data);                           // 多格式写入

    connect(cb, &QClipboard::changed, cb, [] {
        qDebug() << "剪贴板变化:" << QApplication::clipboard()->text().left(50);
    });
}

托盘必须检测 isSystemTrayAvailable()——某些 Linux 桌面环境(如部分 GNOME 配置)默认没有托盘区,硬编码使用会导致图标"消失"。macOS 上还有个特殊约定:图标应使用模板图(黑色带透明度),系统会自动适配明暗菜单栏。

QClipboard 区分三种模式:Clipboard(Ctrl+C/V)、Selection(X11 鼠标选中即复制)、FindBuffer,其中 Selection 在非 X11 平台无效。

#命令行解析 QCommandLineParser

C++
#include <QCoreApplication>
#include <QCommandLineParser>
#include <QCommandLineOption>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("tool");
    QCoreApplication::setApplicationVersion("1.0.0");

    QCommandLineParser parser;
    parser.setApplicationDescription("一个示例命令行工具");
    parser.addHelpOption();                       // -h / --help
    parser.addVersionOption();                    // -v / --version

    // 带值的选项:短名、长名、描述、值名、默认值
    parser.addOption(QCommandLineOption({"o", "output"},
                                        "输出文件路径", "output", "out.txt"));
    parser.addOption(QCommandLineOption({"f", "format"},
                                        "输出格式", "format", "json"));
    // 开关型选项
    parser.addOption(QCommandLineOption("verbose", "输出详细日志"));
    // 位置参数
    parser.addPositionalArgument("input", "输入文件路径");

    parser.process(app);                          // 出错会自动打印并退出

    const QStringList args = parser.positionalArguments();
    if (args.isEmpty()) {
        parser.showHelp(1);                       // 缺参数 → 帮助 + 退出码 1
    }

    qDebug() << args.first()
             << parser.value("output")
             << parser.value("format")
             << parser.isSet("verbose");
    return 0;
}

parser.process(app) 会自动处理 -h/--version,解析失败时直接退出进程,因此必须放在业务逻辑之前。

#国际化:QTranslator 与 linguist

Qt 的国际化流程是编译期提取 + 运行期加载,标准工作流五步:

  1. 代码里用 tr()(或 QCoreApplication::translate())包裹所有用户可见字符串;
  2. CMake 中声明 .ts 文件,构建时 lupdate 提取待翻译文本;
  3. 用 Qt Linguist 翻译,生成 .ts;
  4. lrelease 编译为 .qm(二进制,体积小、加载快);
  5. 运行时 QTranslator::load() + installTranslator()。
C++
// ===== 文件 1:main.cpp =====
#include <QApplication>
#include <QTranslator>
#include <QLibraryInfo>
#include <QLocale>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // 先装 Qt 自带控件的翻译(QMessageBox 的按钮等)
    QTranslator qtBase;
    if (qtBase.load("qtbase_" + QLocale::system().name(),
                    QLibraryInfo::path(QLibraryInfo::TranslationsPath))) {
        app.installTranslator(&qtBase);
    }

    // 再装本应用的翻译(qm 放在资源里,部署无忧)
    QTranslator appTrans;
    if (appTrans.load(QString(":/i18n/app_%1.qm").arg(QLocale::system().name()))) {
        app.installTranslator(&appTrans);
    } else {
        qWarning() << "翻译加载失败";
    }

    return app.exec();   // 之后的 tr() 自动生效
}

CMake 侧用内置函数自动处理 lupdate 与 lrelease:

CMake
cmake_minimum_required(VERSION 3.16)
project(I18nDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets LinguistTools)

qt_add_executable(I18nDemo main.cpp mainwindow.cpp)

qt_add_translations(I18nDemo
    TS_FILES
        i18n/app_zh_CN.ts
        i18n/app_en_US.ts
)

target_link_libraries(I18nDemo PRIVATE Qt6::Widgets)

qt_add_translations() 会在构建时自动运行 lupdate 更新 .ts(把新增的 tr() 字符串提取进去),再运行 lrelease 把 .ts 编译成 .qm;通过 QM_FILES_RESOURCE_PREFIX 参数还能让 .qm 自动嵌入资源系统,部署时彻底不用管翻译文件。注意它来自 LinguistTools 组件,find_package 时别漏掉。需要 D-Bus 时再额外链接 Qt6::DBus,并用前面说的 if(UNIX AND NOT APPLE) 条件包裹。

#tr() 的几个坑

问题说明
字符串拼接tr("共 " + n) 无法翻译,要用 tr("共 %1").arg(n)
类外使用非 QObject 子类中用 QCoreApplication::translate("Context", "...")
复数用 tr("%n 个文件", "", n),Qt 自动处理复数形式
动态生成运行时拼出的字符串无法被提取,要预先枚举

#资源系统 qrc 深入

.qrc 把资源编译进可执行文件,避免"程序找不到图标"的部署噩梦。

C++
// ===== 文件 1:resources.qrc =====
// <RCC>
//     <qresource prefix="/">
//         <file>icons/app.svg</file>
//         <file>icons/open.svg</file>
//         <file>styles/dark.qss</file>
//     </qresource>
//
//     <!-- 按语言分组,配合 Linguist 使用 -->
//     <qresource prefix="/i18n">
//         <file alias="app_zh_CN.qm">i18n/app_zh_CN.qm</file>
//     </qresource>
// </RCC>

// ===== 文件 2:资源访问 =====
#include <QApplication>
#include <QCoreApplication>
#include <QFile>
#include <QIcon>
#include <QDir>
#include <QDebug>

void resourceDemo()
{
    QIcon icon(":/icons/app.svg");                 // 图标
    if (QFile::exists(":/icons/app.svg")) {        // 存在性判断
        qDebug() << "资源存在";
    }

    QFile f(":/styles/dark.qss");                  // 读取 QSS
    if (f.open(QIODevice::ReadOnly | QIODevice::Text)) {
        qApp->setStyleSheet(QString::fromUtf8(f.readAll()));
    }
}

// 大素材外置:开发期在构建目录旁,部署期在可执行文件旁
QString assetPath(const QString &relative)
{
    return QDir(QCoreApplication::applicationDirPath()).filePath(relative);
}
特性说明
prefix虚拟目录,代码中通过 :/prefix/path 访问
alias重命名资源,使代码路径与实际目录解耦
lang 属性<qresource lang="zh_CN"> 实现按语言自动选择
压缩Qt 6 中可配合 CMAKE_AUTORCC 与压缩选项减小体积

资源路径始终以 : 开头,且大小写敏感(即使在 Windows 上)。这是跨平台时最容易踩的坑——Windows 开发时 :/Icons/App.svg 能跑,到 Linux 上就失效了。

经验法则:图标、翻译、QSS 进 qrc(小且需要绝对可靠);大素材外置(方便替换、不撑大二进制)。把资源编进可执行文件会让二进制变大,且每次改资源都要重新链接,几十 MB 的音视频素材尤其不适合放进 qrc。

Qt 5 提示:Qt 6 中 QLibraryInfo::path(QLibraryInfo::TranslationsPath) 取代了 Qt 5 的 QLibraryInfo::location();翻译方面用 qt_add_translations() 取代 Qt 5 的 qt5_create_translation() / qt5_add_translation()。此外 Qt 6 的 QProcess::start() 不再支持单字符串命令,必须传 QStringList 参数。

#小结

  1. QProcess 用 start() 异步启动,参数走 QStringList 避免路径空格问题;必须读取输出否则可能死锁子进程。
  2. QLocalServer/QLocalSocket 是同机 IPC 首选,单实例应用的标准实现是"尝试监听 → 失败则转发参数并退出"。
  3. QSharedMemory 适合大数据共享,但不能存指针(不同进程地址空间不同),需配 QSystemSemaphore 同步。
  4. 托盘要检测 isSystemTrayAvailable();国际化流程是 tr() → lupdate → Linguist → lrelease → 运行时 installTranslator()。
  5. qrc 资源路径以 : 开头且大小写敏感;小资源入 qrc、大素材外置到 applicationDirPath()。

#练习

  1. 用 QProcess 写一个"命令执行器":输入命令实时显示输出到 QPlainTextEdit,支持"停止"按钮(kill())和退出码显示。
  2. 实现单实例应用:第二个实例启动时把命令行参数通过 QLocalSocket 发给第一个实例,主实例收到后打开对应文件。
  3. 用 QSharedMemory + QSystemSemaphore 在两个进程间传递一张 QImage(提示:QBuffer + QDataStream 序列化),并处理"共享内存已存在但尺寸不足"的情况。
  4. 给一个已有程序加上完整国际化支持:把所有界面字符串改为 tr(),配置 qt_add_translations() 生成中英文 ts,用 Linguist 翻译后验证切换系统语言时界面自动切换。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。