一次 Qt 程序在 Kylin 系统下表头“白屏”的排查之旅

一次 Qt 程序在 Kylin 系统下表头"白屏"的排查之旅

明明代码没动过，Windows 下岁月静好，一到 Kylin（麒麟）系统，QTableView 的表头就变成了"一片白板"。这究竟是人性的扭曲，还是 Qt 的 Bug？

背景

最近在做一个跨平台的项目，需要同时支持 Windows 和国产 Kylin 系统。代码在 Windows 上用 VS 编译运行，界面一切正常。结果把程序挪到 Kylin 虚拟机上一跑，好家伙，QTableView 的表头直接"隐身"了------背景全白，文字还在但几乎看不清，就跟没有表头似的。

现象回顾

Windows 环境：表头显示正常，有灰色的立体感背景。
Kylin 环境：表头背景纯白，与表格背景混为一体，只有点击时才有反馈。
代码：完全一致，没有设置特殊的样式表（QSS）。

![想象中的对比图：左边正常灰表头，右边全白表头]

排查过程

1. 第一反应：是不是样式表没写？

赶紧在代码里给 QHeaderView::section 加了个背景色，结果发现：加是有效的，但为什么默认会是白的？

2. 发现端倪：`QT_QPA_PLATFORMTHEME`

在排查环境变量时，我发现了一个叫 QT_QPA_PLATFORMTHEME 的东西。在编译环境（Kylin 终端）下 echo 一下，输出是 ukui。而在运行环境（直接双击启动）下，这个变量竟然是空的。

灵魂拷问：这个变量到底是编译时起作用，还是运行时起作用？

结论：运行时。 编译环境设置的值不会被编进 exe 里。运行时变量为空，不代表没有主题，恰恰相反------在 Kylin 系统上，空值反而意味着"让 Qt 自己去猜"，结果 Qt 猜成了"我要加载 UKUI 原生主题"。

3. 真相大白：UKUI 主题的"强制接管"

Kylin 系统（尤其是 UKUI 桌面环境）为了让所有软件看起来像"原生麒麟软件"，提供了一个 Qt 平台主题插件。这个插件会覆盖 Qt 默认的控件绘制，包括把表头背景强制刷成系统主题色------也就是白色。

这就解释了为什么 Windows 下没事：Windows 没有 UKUI 主题插件，Qt 老老实实用自己的 Windows 样式。

解决方案

试了几种方法，各有优劣，我把它们都列出来供大家参考。

方案一：样式表硬刚（治标）

直接给表头设置样式表，优先级拉满。

cpp 复制代码

tableView->horizontalHeader()->setStyleSheet(
    "QHeaderView::section {"
    "    background-color: #f0f0f0;"
    "    border: 1px solid #dcdcdc;"
    "}"
);

效果：有效，但如果整个程序很多表头都要改，写起来挺烦的。

方案二：环境变量劝退（玄学）

在启动脚本里强制清空主题变量。

bash 复制代码

export QT_QPA_PLATFORMTHEME=""
./your_app

效果：不稳定，有时候 Kylin 还是会在其他地方加载主题。

方案三：强制使用 Fusion 样式（真·大招）

这是我最后采用的方法。直接在 main 函数里告诉 Qt："别管系统是什么，给我穿上 Fusion 这件衣服"。

cpp 复制代码

#include <QStyleFactory>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    
    // 就是这一句，强行锁死样式
    a.setStyle(QStyleFactory::create("Fusion"));
    
    // ... 其他代码
    return a.exec();
}

为什么这招最管用？

Fusion 是 Qt 自带的、完全由 Qt 自己绘制的跨平台样式。它不依赖 Windows 的 comctl32.dll，也不依赖 Kylin 的 libukui。用了它，你的程序在哪儿跑都长得一模一样，彻底告别"环境差异导致的白屏"。

知识点复盘（面试官可能会问）

什么是 Fusion 样式？

是 Qt 内置的一套全平台一致的渲染引擎，不调操作系统的原生 API，所以能保证跨平台 UI 统一。
为什么 Kylin 下默认表头是白的？

因为 UKUI 桌面环境提供了 qt5-ukui-platformtheme 插件，它会接管 Qt 程序的绘制，将表头背景色强制设为了系统主题色（白色）。
环境变量 QT_QPA_PLATFORMTHEME 是干嘛的？

告诉 Qt 运行时加载哪个平台主题插件。设为 ukui 加载麒麟主题，设为 "" 或不设则走系统默认逻辑（在麒麟下默认可能还是会加载）。

写在最后

这次踩坑让我深刻体会到：所谓"跨平台"，不是代码能编译过就行，而是运行时体验要一致。 Kylin 为了生态统一帮我们"美化"了界面，但在特定场景下反而破坏了 UI 的可用性。

如果你也遇到了类似的"白屏"、"样式错乱"问题，不要急着怀疑代码，先试试 a.setStyle(QStyleFactory::create("Fusion"));。这一行代码，值得加入你的跨平台 Qt 程序模板里。

代码千万行，兼容第一行。样式不规范，同事两行泪。

一次 Qt 程序在 Kylin 系统下表头“白屏”的排查之旅