银河麒麟/Linux 环境下 Qt6 应用程序中文输入法（Fcitx）适配与发布指南

1. 问题背景与现象

在银河麒麟（Kylin OS）等 Linux 系统中，使用自定义安装的 Qt6（如 Qt 6.2.4）进行 C++ 桌面应用程序开发时，经常遇到以下中文输入法兼容性问题：

• 现象：系统自带的其他软件可正常使用搜狗输入法/Fcitx 框架，但 Qt6 应用程序在聚焦输入框时，右下角弹出 “无输入窗口” (No input window) 提示，无法输入中文。
• 诊断方法：在启动程序时追加环境变量 QT_DEBUG_PLUGINS=1。查看控制台输出，会发现程序未能加载 fcitx 的平台输入上下文插件（platforminputcontexts），只能回退加载基础的 compose 插件。
• 核心原因：系统默认只提供了基于 Qt5 编译的 Fcitx 插件，而 Qt6 程序无法加载 Qt5 插件（ABI/API 不兼容）。官方软件源往往缺乏现成的 fcitx-frontend-qt6，导致 Qt6 程序无法与 Fcitx 输入法框架建立通信通道。此外，Wayland 显示服务器以及 IDE（如 CLion）未继承系统环境变量也会导致该问题。

---

2. 开发环境解决方案（源码编译插件）

在开发环境（如 CLion + 本地 Qt6 编译器）中，最彻底的解决方案是：使用本机 Qt6 重新编译 Fcitx 插件。

2.1 安装编译依赖环境

编译 Fcitx-Qt 插件需要构建工具、KDE 的额外 CMake 模块（ECM）、X11 键盘映射库以及 Fcitx 的开发包。在终端执行：

sudo apt update
sudo apt install build-essential cmake git
sudo apt install extra-cmake-modules
sudo apt install libxkbcommon-dev libxkbcommon-x11-dev
sudo apt install fcitx-libs-dev

2.2 获取 Fcitx-Qt 源码

开源仓库 fcitx-qt5 内部包含了支持 Qt6 的 CMake 构建脚本：

cd ~
git clone https://github.com/fcitx/fcitx-qt5.git
cd fcitx-qt5

2.3 配置 CMake 并编译 Qt6 插件

创建 build 目录。关键操作：关闭 Qt4 和 Qt5 的编译选项，强制开启 Qt6，并指定本地 Qt6 安装路径。

mkdir build && cd build

# 假设 Qt6 安装路径为 /home/clea/Qt/6.2.4/gcc_64
cmake .. -DENABLE_QT4=OFF -DENABLE_QT5=OFF -DENABLE_QT6=ON -DCMAKE_PREFIX_PATH=/home/clea/Qt/6.2.4/gcc_64

# 开始编译
make -j4

编译成功后，将在 build/qt6/platforminputcontext/ 目录下生成 libfcitxplatforminputcontextplugin.so。

2.4 部署插件至本地 Qt 目录

将生成的 .so 文件拷贝到本地 Qt 编译器的插件目录中：

cp qt6/platforminputcontext/libfcitxplatforminputcontextplugin-qt6.so /home/clea/Qt/6.2.4/gcc_64/plugins/platforminputcontexts/

2.5 配置 IDE 环境变量 (CLion 示例)

为了让 IDE 启动的进程知晓输入法框架，必须在 IDE 的 “运行/调试配置” (Edit Configurations) 的 Environment variables 中显式指定：

QT_IM_MODULE=fcitx;XMODIFIERS=@im=fcitx;GTK_IM_MODULE=fcitx;QT_QPA_PLATFORM=xcb

注意：QT_QPA_PLATFORM=xcb 用于强制程序使用 X11 模式运行，可有效规避 Wayland 环境下输入法漂移或失效的 Bug。

至此，开发环境下的中文输入问题已完全解决。

---

3. 生产环境打包与发布指南

在开发环境解决问题后，发布应用程序时必须将环境变量与插件一同打包，确保目标用户在裸机上也能正常输入中文。

3.1 方案 A：代码级注入环境变量（推荐方案）

直接在 main.cpp 中注入环境变量。这种方式对用户完全无感，无需编写额外的 Shell 启动脚本，且能避免污染用户的系统级环境变量。

#include <QApplication>
#include <QProcessEnvironment>

int main(int argc, char *argv[])
{
    // 1. 设置输入法环境变量 (仅当系统环境变量为空时才覆盖)
    if (qEnvironmentVariableIsEmpty("QT_IM_MODULE")) {
        qputenv("QT_IM_MODULE", "fcitx");
    }
    if (qEnvironmentVariableIsEmpty("XMODIFIERS")) {
        qputenv("XMODIFIERS", "@im=fcitx");
    }
    if (qEnvironmentVariableIsEmpty("GTK_IM_MODULE")) {
        qputenv("GTK_IM_MODULE", "fcitx");
    }

    // 2. 强制使用 xcb 平台规避 Wayland 兼容性问题
    if (qEnvironmentVariableIsEmpty("QT_QPA_PLATFORM")) {
        qputenv("QT_QPA_PLATFORM", "xcb");
    }

    // 注意：以上 qputenv 必须写在 QApplication 实例化之前！
    QApplication a(argc, argv);
    
    // 3. 告诉程序去可执行文件同级的 plugins 目录寻找插件
    a.addLibraryPath(QCoreApplication::applicationDirPath() + "/plugins");
    
    // ... 其他初始化与业务逻辑 ...

    return a.exec();
}

3.2 方案 B：编写 Shell 启动脚本

如果希望通过脚本灵活控制，可创建 start.sh 作为程序的入口：

#!/bin/bash
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

export QT_IM_MODULE=fcitx
export XMODIFIERS="@im=fcitx"
export GTK_IM_MODULE=fcitx
export QT_QPA_PLATFORM=xcb

exec "$DIR/YourAppExecutable" "$@"

3.3 携带输入法插件发布（最关键环节）

无论是 linuxdeployqt 还是其他打包工具，通常都不会自动抓取输入法插件。发布前，必须手动将第二步编译出的 libfcitxplatforminputcontextplugin.so 放入程序的发布包中。

最终发布的文件夹结构必须如下所示：

AppReleaseFolder/
├── YourAppExecutable               # 你的可执行文件
├── start.sh                        # 启动脚本 (可选)
└── plugins/                        # 必须包含 plugins 文件夹
    └── platforminputcontexts/
        ├── libcomposeplatforminputcontextplugin.so
        └── libfcitxplatforminputcontextplugin.so  # ← 刚才手动编译的 Qt6 fcitx 插件

提示：配合 3.1 步骤中的 a.addLibraryPath() 代码，程序在目标用户的电脑上启动时，会自动加载这个自带的 Fcitx 插件，从而完美实现中文输入。