一、配置环境变量1、方法1于终端中配置环境变量在启动YourApp之前于当前终端中配置环境变量export QTDIR~/Qt5.14.2/5.14.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins export QML2_IMPORT_PATH$QTDIR/qml export QT_IM_MODULEqtvirtualkeyboard export QT_QPA_PLATFORMxcb然后再运行cd /Your/Software/build/Bin ./YourApp2、方法2于代码中添加环境变量设置 [推荐]qputenv(QT_IM_MODULE, QByteArray(qtvirtualkeyboard));注意上述代码一定要放在你app创建的前面即放在下述代码前面。QGuiApplication app(argc, argv);二、问题分析从运行日志和目录检查结果中一步步推出来下面逐条分析1、“QtQuick.VirtualKeyboard 主模块有”依据在执行ls ~/Qt5.14.2/5.14.2/gcc_64/qml/QtQuick/VirtualKeyboard输出是libqtquickvirtualkeyboardplugin.so plugins.qmltypes qmldir Settings Styles其中 qmldir 是 QML 模块的定义文件。一个目录里有 qmldir就说明这个 QML 模块被正确安装了。所以可以确定 QtQuick.VirtualKeyboard 主模块存在。2、“QtQuick.VirtualKeyboard.Styles、Settings 子模块有”依据同样在上面的 ls 输出里可以看到 Settings 和 Styles 两个子目录。并且你执行了find ~/Qt5.14.2 -name qmldir -path VirtualKeyboard 2/dev/null输出里有/home/yourname/Qt5.14.2/5.14.2/gcc_64/qml/QtQuick/VirtualKeyboard/Styles/qmldir /home/yourname/Qt5.14.2/5.14.2/gcc_64/qml/QtQuick/VirtualKeyboard/Settings/qmldir这两个子目录下都有 qmldir说明它们也被安装了。3、“但 QtQuick.VirtualKeyboard.Plugins 子模块没有安装到 qml/ 目录下”依据还是上面那条 find 命令它专门找所有路径里带 VirtualKeyboard 的 qmldir 文件。结果只有三个.../VirtualKeyboard/qmldir .../VirtualKeyboard/Styles/qmldir .../VirtualKeyboard/Settings/qmldir没有出现 “.../VirtualKeyboard/Plugins/qmldir”。如果 Plugins 子模块被安装了就一定会有这个文件。因此可以断定QtQuick.VirtualKeyboard.Plugins 没有安装到 qml/ 目录下。4、“而 Keyboard.qml 第 38 行有一句 import QtQuick.VirtualKeyboard.Plugins 2.14”依据在执行grep -rl VirtualKeyboard.Plugins ~/Qt5.14.2/5.14.2/Src/qtvirtualkeyboard/src/ 2/dev/null输出里包含/home/yourname/Qt5.14.2/5.14.2/Src/qtvirtualkeyboard/src/virtualkeyboard/content/components/Keyboard.qml这说明源码中的 Keyboard.qml 文件里确实引用了 VirtualKeyboard.Plugins。另外在最早的运行日志里有一行错误qrc:/QtQuick/VirtualKeyboard/content/components/Keyboard.qml:38 module QtQuick.VirtualKeyboard.Plugins is not installed这直接指出Keyboard.qml 第 38 行尝试导入 QtQuick.VirtualKeyboard.Plugins但系统报告该模块未安装。5、“这个 import 失败后Keyboard.qml 加载失败 → InputPanel.qml 加载失败 → Login.qml 加载失败 → StackView.initialItem 加载失败 → 整个界面白屏”依据全部来自你最早提供的运行日志。日志里的错误是链式出现的qrc:/main.qml:30:9: QML StackView: initialItem: qrc:/YourActivity/main.qml:21 Type Login unavailable qrc:/YourActivity/Login.qml:130 Type InputPanel unavailable qrc:/QtQuick/VirtualKeyboard/content/InputPanel.qml:127 Type Keyboard unavailable qrc:/QtQuick/VirtualKeyboard/content/components/Keyboard.qml:38 module QtQuick.VirtualKeyboard.Plugins is not installed从下往上读1Keyboard.qml 因为缺少 QtQuick.VirtualKeyboard.Plugins 而加载失败2于是 InputPanel.qml 里用到的 Keyboard 类型不可用InputPanel 加载失败3于是 Login.qml 里用到的 InputPanel 类型不可用Login 加载失败4于是 main.qml 里 StackView 的 initialItem即 Login不可用5最终整个界面无法显示表现为白屏。所以“白屏”不是显卡或窗口系统的问题而是 QML 组件链式加载失败导致的。三、环境变量逐行解释执行的这组命令export QTDIR~/Qt5.14.2/5.14.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins export QML2_IMPORT_PATH$QTDIR/qml export QT_IM_MODULEqtvirtualkeyboard export QT_QPA_PLATFORMxcb1、export QTDIR~/Qt5.14.2/5.14.2/gcc_64作用定义一个名为 QTDIR 的环境变量值为你的 Qt 5.14.2 安装目录。为什么这么做后面几行都要引用这个目录。先定义成一个变量写起来短改起来也方便。如果以后换了 Qt 版本只改这一行就行。export 的含义把变量导出到当前 shell 及其子进程中。这样你启动的YourApp才能读到这些变量。2、export PATHQTDIR/bin:PATH作用把 $QTDIR/bin 加到 PATH 的最前面。为什么这么做PATH 决定了你在终端里输入命令时系统去哪些目录找可执行文件。把 Qt 的 bin 放最前面可以保证你运行 qmake、moc、uic 等工具时优先使用你安装的 Qt 5.14.2 版本而不是系统自带的 Qt。$PATH 放在后面保留原来的搜索路径只是让 Qt 的路径优先。3、export LD_LIBRARY_PATHQTDIR/lib:LD_LIBRARY_PATH作用告诉动态链接器在加载 .so 共享库时优先去 $QTDIR/lib 里找。为什么这么做YourApp依赖很多 Qt 库比如 libQt5Core.so、libQt5Gui.so、libQt5Qml.so 等。系统里可能装了别的 Qt 版本如果不指定程序可能链接到系统 Qt导致版本不匹配、符号找不到、崩溃或白屏。把 $QTDIR/lib 放最前面就能保证程序使用你安装的 Qt 5.14.2 的库。4、export QT_PLUGIN_PATH$QTDIR/plugins作用指定 Qt 插件的搜索路径。为什么这么做Qt 有很多插件比如平台插件platforms/libqxcb.so、输入法插件platforminputcontexts/libqtvirtualkeyboardplugin.so等。QT_PLUGIN_PATH 会告诉 Qt 去 $QTDIR/plugins 下找这些插件。如果不设置Qt 可能去系统目录找而系统目录里可能没有虚拟键盘插件或者版本不对。你之前检查过 $QTDIR/plugins/platforminputcontexts/ 下有 libqtvirtualkeyboardplugin.so设置这个变量就能让 Qt 找到它。5、export QML2_IMPORT_PATH$QTDIR/qml作用指定 QML 模块的搜索路径。为什么这么做QML 引擎在解析 import QtQuick.VirtualKeyboard 2.14 这类语句时会去 QML2_IMPORT_PATH 指定的目录里找对应的模块。你的虚拟键盘 QML 模块安装在 $QTDIR/qml/QtQuick/VirtualKeyboard。如果不设置这个变量QML 引擎可能去系统 QML 目录找那里可能没有安装或者版本不对。设置后它就能找到你安装的虚拟键盘模块InputPanel、Keyboard 等组件才能正常加载。这是解决白屏的关键之一。6、export QT_IM_MODULEqtvirtualkeyboard作用指定 Qt 的输入法模块为 qtvirtualkeyboard。为什么这么做QML 中的 InputPanel 是虚拟键盘的输入面板它依赖 Qt 的输入法框架。QT_IM_MODULE 告诉 Qt 使用哪个输入法插件。设置为 qtvirtualkeyboard 后Qt 才会加载虚拟键盘作为输入法InputPanel 才能正常工作。如果不设置InputPanel 可能找不到输入法后端导致加载失败。这也是解决白屏的关键之一。7、export QT_QPA_PLATFORMxcb作用指定 Qt 的平台插件为 xcb也就是使用 X11 后端。为什么这么做你最早的日志里有一行警告Warning: Ignoring XDG_SESSION_TYPEwayland on Gnome. Use QT_QPA_PLATFORMwayland to run on Wayland anyway.这说明你的桌面环境是 Wayland但 Qt 默认可能没有正确适配或者虚拟键盘在 Wayland 下有问题。强制使用 xcbX11 后端可以避开 Wayland 的兼容性问题让界面稳定显示。在很多 Qt 应用白屏、闪烁、输入法异常的情况下切到 xcb 是常见的解决办法。8、总结这些变量为什么能解决白屏1QML2_IMPORT_PATH 让 QML 引擎找到了 QtQuick.VirtualKeyboard 模块2QT_IM_MODULE 让 InputPanel 能挂上虚拟键盘输入法3QT_PLUGIN_PATH 让 Qt 找到了虚拟键盘的平台输入法插件4LD_LIBRARY_PATH 保证程序用的是你安装的 Qt 5.14.2 库5QT_QPA_PLATFORMxcb 避开了 Wayland 的潜在问题。这些条件同时满足后Keyboard.qml 不再因为缺少模块而失败链式加载恢复正常界面就不再白屏了。9、补充建议这些 export 只在当前终端有效。关掉终端或换一个终端就需要重新执行。建议把它们写进一个启动脚本例如#!/bin/bash export QTDIR~/Qt5.14.2/5.14.2/gcc_64 export PATHQTDIR/bin:PATH export LD_LIBRARY_PATHQTDIR/lib:LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins export QML2_IMPORT_PATH$QTDIR/qml export QT_IM_MODULEqtvirtualkeyboard export QT_QPA_PLATFORMxcb cd /Your/Software/build/Bin ./YourApp保存为 run.sh然后 chmod x run.sh以后用 ./run.sh 启动即可。