Ubuntu Wayland 下安装与配置 Fcitx5 中文输入法教程

适用场景

本教程适用于 Ubuntu 桌面环境，尤其是默认使用 Wayland 会话的系统。如果你的终端执行 echo $XDG_SESSION_TYPE 输出 wayland，按本文步骤操作即可。若输出 x11，环境变量部分需改用 X11 方案，本文会在相应位置注明。

Wayland 下配置 Fcitx5 的核心原则只有一条：只设置 XMODIFIERS，不要全局设置 GTK_IM_MODULE。这样 GTK 应用可以走 Wayland 原生的输入协议，避免兼容性问题。

第一步：清理旧版 Fcitx4（可选）

Fcitx5 与 Fcitx4 是相互独立的框架，如果系统中残留旧版，可能引起冲突。先检查：

dpkg -l | grep fcitx | grep -v fcitx5

如果没有输出，说明系统干净，直接进入下一步。如果有输出，执行卸载并清理：

sudo apt purge fcitx* -y
sudo apt autoremove -y

完成后建议注销并重新登录，确保旧框架完全退出。

第二步：安装 Fcitx5 及中文组件

更新软件源后，一次性安装框架、中文输入引擎和应用前端模块：

sudo apt update
sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5 -y

其中 fcitx5-chinese-addons 提供拼音、双拼等中文输入引擎；frontend-* 系列确保 Fcitx5 能在 GTK 和 Qt 应用中正常唤起。

第三步：设为系统默认输入法框架

使用 im-config 将 Fcitx5 设为默认：

im-config -n fcitx5

命令无输出即表示设置成功。

第四步：配置 Wayland 环境变量

Wayland 下只需要设置 XMODIFIERS，用于 XWayland 下的 X11 应用。推荐写入 environment.d，使其对所有会话生效：

sudo mkdir -p /etc/environment.d
echo 'XMODIFIERS DEFAULT=@im=fcitx' | sudo tee /etc/environment.d/90-fcitx5.conf

请不要全局设置 GTK_IM_MODULE=fcitx 或 QT_IM_MODULE=fcitx。Wayland 下强制设置 GTK_IM_MODULE 可能干扰 GTK 原生输入协议，反而导致部分应用无法输入中文。个别 Qt 应用若确实需要，可对该应用单独设置启动变量，后文会说明。

如果你使用的是 X11 会话，则需要设置 GTK_IM_MODULE、QT_IM_MODULE 和 XMODIFIERS 三个变量。本文以 Wayland 为准。

第五步：GNOME 桌面额外设置

如果你使用的是 Ubuntu 默认的 GNOME 桌面，执行以下命令，让 GTK 应用正确加载 Fcitx5 输入模块：

gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"

非 GNOME 桌面可跳过此步。

第六步：重启系统

环境变量和 gsettings 的修改需要完整重启才能生效：

sudo reboot

第七步：重启后验证

登录后，依次执行以下检查：

# 检查 Fcitx5 是否在运行
pgrep -a fcitx5

# 检查环境变量
env | grep -E "IM_MODULE|XMODIFIERS"

# 检查 im-config 当前设置
im-config -l

预期结果是：fcitx5 进程存在；环境变量中能看到 XMODIFIERS=@im=fcitx；不应出现 GTK_IM_MODULE=fcitx；im-config -l 显示 fcitx5。

如果 Fcitx5 没有自动启动，可以手动启动并设为登录自启：

fcitx5 -d
mkdir -p ~/.config/autostart
cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart/

第八步：添加拼音输入法

打开 Fcitx5 配置工具：

fcitx5-configtool

在“输入法”选项卡中，取消勾选“仅显示当前语言”，在可用列表中找到“拼音”，点击箭头添加到左侧“当前输入法”列表，最后点击“应用”。

之后使用 Ctrl + Space 即可切换中英文输入。

第九步：避免与 GNOME 输入源冲突

打开“设置 → 键盘 → 输入源”，如果列表中仍有“中文（智能拼音）”等 IBus 输入源，建议移除，只保留 Fcitx5 作为输入法框架，避免两套输入法同时响应导致切换异常。

常见问题与处理

1. 重启后仍存在 GTK_IM_MODULE=fcitx

说明有其他配置文件设置了该变量。用以下命令排查：

grep -rn "GTK_IM_MODULE" ~/.profile ~/.rc ~/._profile /etc/environment 2>/dev/null

找到后删除或注释掉，重新登录。

2. 个别 Qt 应用无法输入中文

不要全局设置 QT_IM_MODULE，可以只对该应用单独启动：

QT_IM_MODULE=fcitx 应用名

例如：

QT_IM_MODULE=fcitx qtcreator

3. Electron 应用无法输入中文

以 VS Code 为例，可在 ~/.config/code-flags.conf 中加入：

text

--ozone-platform=wayland
--enable-wayland-ime

其他 Electron 应用的启动参数配置位置不同，可查阅对应文档。

总结

整套流程可以概括为：清理旧版 → 安装 Fcitx5 与中文组件 → im-config 设为默认 → 写入 XMODIFIERS → GNOME 设置 Gtk/IMModule → 重启 → 验证 → 用 fcitx5-configtool 添加拼音。按顺序执行完毕，Ubuntu Wayland 下的 Fcitx5 中文输入即可正常使用。