Windows 上跑得好好的,Linux 上崩了?跨平台适配的 10 个坑

Aether 跨平台实战记录

一、一个"完美"的周五下午

周五下午 4 点 57 分。我泡好咖啡，准备摸鱼下班。

Windows 上跑了两个月了，200 多个测试用例全部通过。CI 绿得像翡翠。客户下周一在 Linux 上部署，我跟领导拍胸脯说 Qt 是跨平台的，改个编译器就完事。

4 点 59 分。我 ssh 登上了 Linux 编译服务器。

mkdir build && cd build && cmake .. && make -j8

编译通过了。我笑了笑，Qt 的跨平台果然不是吹的。

5 点 03 分。./aether

段错误。

5 点 05 分。插件加载失败，日志全是乱码，信号没连上，明明存在的配置文件说找不到，socket 连接秒断，线程名变成了乱码，CloseEvent 没触发，析构走了一半炸了，core dump 文件占了 8 个 G。

5 点 30 分。咖啡凉了。我盯着满屏的 Segmentation fault，怀疑人生。

你不是一个人。

如果你也经历过"Windows 上一切正常，Linux 上全是 bug"的绝望，这篇就是给你看的。Aether 在跨平台适配过程中踩了刚好 10 个坑，一个不少。

二、10 个坑，每个都出过 bug

坑 1：路径分隔符——\ 还是 /

最蠢的 bug。最痛的代价。

// ❌ Windows 专用的硬编码
QString configPath = "D:\\aether\\config\\app.toml";
QFile file(configPath);
// Linux 上直接炸——目录不存在 / 路径里带反斜杠

// ✅ Qt 帮你跨平台
QString configPath = QStandardPaths::writableLocation(
    QStandardPaths::AppConfigLocation
) + "/app.toml";
// 或者用 QDir 的跨平台分隔符
QString configPath = QDir::toNativeSeparators(
    QCoreApplication::applicationDirPath()
    + "/../config/app.toml"
);

教训：永远不要手写路径。QDir、QFileInfo、QStandardPaths 这些类是 Qt 给你的保险。Windows 上反斜杠确实能跑，但换到 Linux 上就是 -1 返回值 + 一堆 File not found。

坑 2：编码问题——GBK 和 UTF-8 打架

Windows 中文版上，Qt Creator 的默认编码是 GBK。你在代码里写了个中文注释，编译过去了。但在 Linux 上，GCC 默认用 UTF-8 解释源文件——中文字符串直接变成乱码。

// ❌ 源文件是 GBK 编码，Linux 上编译
QString title = tr("相机参数设置");
// Linux 运行结果：""（空字符串）或乱码

// ✅ 统一用 UTF-8 with BOM，明确定义编码
// 在 CMakeLists.txt 里加：
// add_compile_options("$<$<C_COMPILER_ID:MSVC>:/utf-8>")
// add_compile_options("$<$<CXX_COMPILER_ID:MSVC>:/utf-8>")
// 源文件另存为 UTF-8 with BOM
QString title = tr("相机参数设置");
// Linux 运行结果：正确显示

更坑的是 QString::toStdString()。Qt 的 QString 是 UTF-16 内部编码，转成 std::string 默认走 QTextCodec::codecForLocale()。Windows 中文版上它会走 GBK，Linux 上走 UTF-8。同一段代码，同一个文件，两个平台的二进制内容不一样。

统一套路： 显式指定编码，别依赖默认行为。

坑 3：编译器差异——MSVC 和 GCC 不是同一个 C++

// ❌ MSVC 能编译，GCC 报错
struct Config {
int value = 0;       // MSVC 允许类内初始化 + 隐式构造
    QString name;        // MSVC 自动生成移动构造函数
};
std::vector<Config> configs;
configs.reserve(10);     // MSVC 上 push_back 正常
// GCC 上编译错误：没有合适的移动构造函数 / 拷贝构造函数被删除

// ✅ GCC 比 MSVC 严格，显式定义
struct Config {
Config() = default;
Config(const Config&) = default;
Config(Config&&) noexcept = default;
    Config& operator=(const Config&) = default;
    Config& operator=(Config&&) noexcept = default;
int value = 0;
    QString name;
};

GCC 对模板的实例化时机更严格，对 ODR 违反的检测更强。MSVC 宽松，很多"看起来能跑"的代码在 GCC 上直接编译不过。

Aether 中踩得最惨的一次：MSVC 上 std::function 的 target type 能正确匹配，GCC 上返回 nullptr。排查了 3 天，最后发现是跨 DLL 边界传递 std::function 时，GCC 的 RTTI 实现不跨动态库共享 typeinfo。

坑 4：动态库加载——.dll vs .so

Windows 上加载插件：LoadLibrary("plugin_core.dll")。Linux 上：dlopen("libplugin_core.so")。

你以为只是后缀名不同？太天真了。

// ❌ Windows 上正常，Linux 上段错误
QLibrary lib("plugin_core");
lib.load();   // Windows 成功，Linux 返回 false
// 原因：Linux 上的 .so 命名是 libplugin_core.so
// QLibrary("plugin_core") 在 Linux 上找的是 plugin_core.so

// ✅ 正确的做法：让 Qt 处理平台差异
QLibrary lib;
#if defined(Q_OS_WIN)
    lib.setFileName("plugin_core");
#elif defined(Q_OS_LINUX)
    lib.setFileName("libplugin_core");
#endif
// 或者更简单——让 QLibrary 自动追加前缀和后缀
lib.setFileName("plugin_core");  // Qt 自动处理

还有更隐蔽的：Linux 上 .so 的符号默认是隐藏的。如果你的插件类要导出给主程序用，必须加 Q_DECL_EXPORT 或写 .def 文件。不然 dlsym 返回 nullptr，插件加载失败，连错误日志都没有。

// Aether 插件导出宏
#if defined(Q_OS_WIN)
#define AETHER_PLUGIN_EXPORT __declspec(dllexport)
#else
#define AETHER_PLUGIN_EXPORT __attribute__((visibility("default")))
#endif

坑 5：信号槽行为差异

Qt 的信号槽机制在 Windows 和 Linux 上行为基本一致。但有一个细节：跨线程的信号槽连接。

// ❌ 在 Linux 上可能触发 assert
Qt::ConnectionType type = Qt::AutoConnection;
// Windows 上：自动判断为 QueuedConnection，正常工作
// Linux 上：某些 GCC 版本中，线程 ID 比较逻辑不一样
// AutoConnection 误判为 DirectConnection，跨线程直接调用
// 导致：对象还在另一个线程上，slot 就执行了——crash

// ✅ 显式指定连接类型
connect(sender, &Sender::signal,
        receiver, &Receiver::slot,
        Qt::QueuedConnection);  // 别偷懒用 Auto

GCC 的 std::thread::id 实现和 MSVC 不一样。MSVC 返回的是整数 ID，GCC 返回的是结构体指针——QThread::currentThreadId() 的底层实现在不同平台上行为不同。保险起见，跨线程通信一律显式指定 Qt::QueuedConnection。

坑 6：线程命名

调试时的好习惯：给每个线程起个名字。

// ❌ Windows 上能设置线程名，Linux 上没反应
QThread* worker = new QThread();
worker->setObjectName("WorkerThread");
// Windows 上：VS Debug 窗口显示 "WorkerThread"
// Linux 上：GDB 里看不到这个名字

// ✅ Linux 上要用 pthread_setname_np
void setThreadName(const char* name)
{
#if defined(Q_OS_LINUX)
pthread_setname_np(pthread_self(), name);
#elif defined(Q_OS_WIN)
// Qt 的 setObjectName 在 Windows 上
// 通过 SetThreadDescription 生效
    QThread::currentThread()->setObjectName(name);
#endif
}

不起眼的问题。但在线上排查线程死锁时，一个个 unnamed thread 让你根本分不清谁是谁。

坑 7：文件系统大小写敏感

Windows 上 Config.toml 和 config.toml 是同一个文件。Linux 上是两个不同的文件。

// ❌ 拼写不一致，Windows 上跑得欢
QString path = configDir + "/Config.toml";
// 但是程序里其他地方写的是：
// QString path = configDir + "/config.toml";
// Windows 上正确打开，Linux 上 FileNotFound

// ✅ 统一文件名大小写，保持一致
// 或者在 CMake 阶段就做检查
// 更彻底的方案：写个测试用例遍历所有资源路径

Aether 的教训：配置文件 AppSettings.toml，Windows 上有人写 appsettings.toml，Linux 上 CI 直接挂了。最后定了条死规矩：所有资源路径一律小写 + 下划线。 谁用驼峰谁改。

坑 8：环境变量

GetEnvironmentVariable vs getenv，一个是宽字符，一个是单字节。

// ❌ 手动获取，平台判断乱
QString path;
#ifdef Q_OS_WIN
wchar_t buf[MAX_PATH];
GetEnvironmentVariableW(L"PATH", buf, MAX_PATH);
    path = QString::fromWCharArray(buf);
#else
char* buf = getenv("PATH");
    path = QString::fromUtf8(buf);
#endif

// ✅ Qt 帮你封装了
QString path = qEnvironmentVariable("PATH");
// 跨平台，自动处理编码
// 如果想带默认值：
QString val = qEnvironmentVariable("AETHER_HOME", "/opt/aether");

qEnvironmentVariable 在 Qt 5.10 之后引入。如果你还在用老版本，自己封装一个。别裸写平台宏，别重复造轮子。

坑 9：套接字 / IO 模型

Windows 上的 IOCP 和 Linux 上的 epoll 都是异步 IO。但 Qt 的 QTcpSocket 封装了这层差异——前提是你的用法正确。

// ❌ 混合使用阻塞和非阻塞，Windows 上正常
QTcpSocket socket;
socket.connectToHost("127.0.0.1", 8080);
socket.waitForConnected(3000);   // 阻塞等连接
socket.write(data);
socket.waitForBytesWritten(3000); // 阻塞等写入

// Linux 上：waitForBytesWritten 可能直接返回 false
// 原因：epoll 模式下，非阻塞 socket 的写入行为不同
// 内核缓冲区大小不一样，EAGAIN 的处理方式不同

// ✅ 统一用事件驱动，别混用
QTcpSocket socket;
connect(&socket, &QTcpSocket::connected, [&]() {
    socket.write(data);
});
connect(&socket, &QTcpSocket::bytesWritten, [&](qint64 bytes) {
// 写入完成回调
});
socket.connectToHost("127.0.0.1", 8080);

核心原则：写了事件循环就别再用 waitFor 系列函数。 Windows 上它可能碰巧能用，Linux 上 epoll 的行为让你死得明明白白。

坑 10：打包部署

最后一个坑，也是最容易被忽视的。

Windows 上 windeployqt 一把梭，把需要的 DLL 全拷过来。Linux 上 ldd 一看，缺这个缺那个。

# ❌ 以为 Qt 的 so 会自动被找到
./aether
# error while loading shared libraries: libQt5Core.so.5

# ✅ 正确做法：设置 rpath 或用 AppImage
# 方案 A：CMake 里设 rpath
set_target_properties(aether PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_RPATH "$ORIGIN/../lib"
)

# 方案 B：用 linuxdeployqt 打 AppImage
# linuxdeployqt aether -appimage

# 方案 C：写个 wrapper 脚本
#!/bin/bash
DIR="$(cd "$(dirname "$0")" && pwd)"
export LD_LIBRARY_PATH="$DIR/../lib:$LD_LIBRARY_PATH"
exec "$DIR/aether" "$@"

更坑的是 Qt 插件的 so 文件：platforms/libqxcb.so 必须在 platforms/ 目录下，且必须能被找到。不然 Qt 启动时直接弹 "Cannot load platform plugin" 就没下文了。

在 Linux 上，一切都要你自己摆好。 没有 Windows 那种"DLL 放旁边就能找到"的好事。

三、Aether 的跨平台策略

踩完这些坑之后，我们总结了一套打法。

CMake 层面：一次配置，两边编译

# 跨平台编译选项
if(WIN32)
    target_compile_definitions(aether PRIVATE AETHER_OS_WIN)
    set(PLATFORM_SOURCES
        src/platform/win/win_utils.cpp
        src/platform/win/registry.cpp
    )
elseif(UNIX AND NOT APPLE)
    target_compile_definitions(aether PRIVATE AETHER_OS_LINUX)
    set(PLATFORM_SOURCES
        src/platform/linux/linux_utils.cpp
        src/platform/linux/dbus.cpp
    )
endif()

# 统一 UTF-8 源码编码
if(MSVC)
    target_compile_options(aether PRIVATE /utf-8)
endif()

# 设置 rpath，方便部署
set_target_properties(aether PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_RPATH "$ORIGIN/../lib"
)