前言 链接到标题

新装了 Ubuntu 26.04，发现中文输入法不好用？本文详细记录了在 Ubuntu 26.04 (GNOME 50, Wayland) 上安装配置 Fcitx5 输入法的完整过程，包含常见的候选词窗口位置飘移问题的解决方案。

环境信息 链接到标题

  • 系统：Ubuntu 26.04 (resolute)
  • 桌面环境：GNOME 50
  • 显示协议：Wayland（默认）
  • 输入法框架：Fcitx5

安装 Fcitx5 及相关组件 链接到标题

1
2

sudo apt update
sudo apt install fcitx5 fcitx5-rime fcitx5-chinese-addons
  • fcitx5：输入法主程序
  • fcitx5-rime：中州韵输入法引擎（Rime，支持拼音/双拼/五笔等）
  • fcitx5-chinese-addons：中文增强组件（云拼音、拼音助手等）

配置方式一：X11 桌面环境 链接到标题

如果使用 X11 作为显示服务器，配置非常简单，设置环境变量即可。

注意：环境变量值使用 fcitx（不带数字 5），因为输入法模块的 .so 文件名是 im-fcitx.so / libfcitxplatforminputcontextplugin.so，GTK_IM_MODULE=fcitx5 会导致模块加载失败。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 写入 ~/.xprofile（登录时加载，对所有 GUI 应用生效）
cat >> ~/.xprofile << 'EOF'
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
export SDL_IM_MODULE=fcitx
EOF

# 设置 fcitx5 为默认输入法
im-config -n fcitx5

# 设置开机自启动
mkdir -p ~/.config/autostart
cat > ~/.config/autostart/fcitx5.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Fcitx5
Exec=fcitx5
Comment=Start Fcitx5 input method
EOF

配置方式二：Wayland + GNOME（本文重点） 链接到标题

注意：在 GNOME + Wayland 下，GTK_IM_MODULE 环境变量不能全局设置，否则会导致候选词窗口位置错乱（“飘"了）。正确的做法是通过 GTK 配置文件来指定输入法模块。

1. 设置系统级环境变量 链接到标题

写入 /etc/environment，这些变量由 display manager 读取并传递给整个用户会话：

1
2
3
4
5

sudo tee /etc/environment << 'EOF'
XMODIFIERS=@im=fcitx
QT_IM_MODULE=fcitx
QT_IM_MODULES=wayland;fcitx
EOF

说明：

  • XMODIFIERS：为 XWayland 应用（如 Chromium、Electron 应用）提供输入法支持
  • QT_IM_MODULE=fcitx：Qt5/Qt6 应用使用 fcitx 输入法模块
  • QT_IM_MODULES=wayland;fcitx：Qt 6.7+ 新增变量，指定输入法模块回退顺序。Ubuntu 26.04 的 Qt 6.10 支持此变量。wayland 优先（使用 text-input-v3 协议），fcitx 作为回退
  • 不要设置 GTK_IM_MODULE，否则 GTK 应用会绕过 Wayland 的原生 text-input-v3 协议，导致候选框定位异常

1.5 清理冲突的环境变量 链接到标题

如果之前按照 X11 方式在 ~/.bashrc 或 ~/.xprofile 中设置了 GTK_IM_MODULE，需要移除它，否则在终端中启动的 GUI 应用仍会读到错误的环境变量：

1
2
3
4
5
6
7
8
9

# 检查 ~/.bashrc 中是否包含 GTK_IM_MODULE
grep -n "GTK_IM_MODULE" ~/.bashrc

# 如果找到，手动删除对应的 export 行
# 或者用 sed 注释掉它：
sed -i 's/^export GTK_IM_MODULE/#export GTK_IM_MODULE/' ~/.bashrc

# 如果有 ~/.xprofile，也检查并清理
grep -n "GTK_IM_MODULE" ~/.xprofile 2>/dev/null

2. 通过 GTK 配置文件设置输入法 链接到标题

对 GTK3 和 GTK4 应用，通过配置文件而非环境变量来指定输入法模块：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# GTK3 配置
mkdir -p ~/.config/gtk-3.0
cat > ~/.config/gtk-3.0/settings.ini << 'EOF'
[Settings]
gtk-im-module=fcitx
EOF

# GTK4 配置
mkdir -p ~/.config/gtk-4.0
cat > ~/.config/gtk-4.0/settings.ini << 'EOF'
[Settings]
gtk-im-module=fcitx
EOF

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

3. 设置开机自启动 链接到标题

1
2
3
4
5
6
7
8

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/fcitx5.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Fcitx5
Exec=fcitx5
Comment=Start Fcitx5 input method
EOF

4. 安装 Kimpanel GNOME 扩展（解决候选框位置问题） 链接到标题

在 Wayland 下，GNOME 使用 ibus dbus 协议与输入法通信。由于 Wayland 没有全局坐标系，输入法无法在正确位置弹出候选词窗口。Kimpanel 扩展作为 GNOME Shell 的一部分运行，能够读取应用窗口的坐标信息，从而在正确位置绘制候选框。

方法一：从网站安装 链接到标题

打开 https://extensions.gnome.org/extension/261/kimpanel/，点击开关安装（需要安装 gnome-browser-connector）。

方法二：命令行安装 链接到标题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 下载并安装
curl -s "https://extensions.gnome.org/extension-info/?pk=261&shell_version=$(gnome-shell --version | grep -oP '\d+\.\d+')" \
  -o /tmp/kimpanel-info.json

DOWNLOAD_URL=$(python3 -c "import json; d=json.load(open('/tmp/kimpanel-info.json')); print(d['download_url'])")
curl -sL "https://extensions.gnome.org$DOWNLOAD_URL" -o /tmp/kimpanel.zip

gnome-extensions install --force /tmp/kimpanel.zip

# 启用扩展
gsettings set org.gnome.shell enabled-extensions \
  "$(gsettings get org.gnome.shell enabled-extensions | sed 's/\]$/,\"kimpanel@kde.org\"/')"

安装后，打开 Extensions（扩展管理器） 应用 —— 如果找不到，安装它：

1

sudo apt install gnome-shell-extension-manager

在扩展管理器中找到 Input Method Panel (Kimpanel)，确保已启用。

5. 注销重新登录 链接到标题

配置完成后，必须注销当前会话并重新登录，原因有二：

  1. /etc/environment 中的环境变量需要新的登录会话才会加载
  2. Kimpanel 扩展需要 GNOME Shell 重启才能生效
  3. GTK 配置文件在应用启动时读取

验证配置 链接到标题

重新登录后，检查环境变量是否生效：

1
2
3
4

echo $XMODIFIERS       # 应为 @im=fcitx
echo $QT_IM_MODULE     # 应为 fcitx
echo $QT_IM_MODULES    # 应为 wayland;fcitx
echo $GTK_IM_MODULE    # 应为空（没有被设置）

如果 GTK_IM_MODULE 非空，说明 ~/.bashrc 或 ~/.xprofile 中仍有旧的配置，请参考步骤 1.5 清理。

检查 Kimpanel 扩展状态：

1
2

gnome-extensions list | grep kimpanel
# 应输出：kimpanel@kde.org

打开 fcitx5-configtool，添加需要的输入法（如 Rime 或 Pinyin）：

1

fcitx5-configtool

常见问题 链接到标题

Q: 候选词窗口仍然不在正确位置 链接到标题

A：先确认 Kimpanel 扩展是否已启用：

1

gnome-extensions list | grep kimpanel

如果没有输出，说明扩展未正确安装或未启用。参考步骤 4 重新安装。

Q: QT_IM_MODULES 环境变量冲突 链接到标题

A：如果按照本文步骤在 /etc/environment 中设置了 QT_IM_MODULES=wayland;fcitx，通常不会冲突。但如果检查发现 QT_IM_MODULES 的值包含 ibus（如 wayland;ibus），说明被 GNOME 会话覆盖了。可以确认 /etc/environment 已正确设置：

1

cat /etc/environment

然后注销重新登录即可。

Q: Electron 应用（VS Code、Chrome）候选框仍飘 链接到标题

A：Electron/Chromium 默认运行在 XWayland 下，通过 XMODIFIERS 工作，候选框位置通常正常。如果使用 Wayland 原生模式运行，需要额外参数：

1
2
3
4
5

# VS Code（推荐 XWayland 模式，默认）
code

# Chrome 使用 Wayland 原生模式（需要 --enable-wayland-ime）
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Q: 输入法无法切换中英文 链接到标题

A：在 fcitx5-configtool 中检查触发键设置，通常默认是 Ctrl+Space。

原理说明 链接到标题

理解 Wayland 下的输入法架构有助于排查问题：

应用 (GTK/Qt/Electron)
       │
       ├── text-input-v3 协议 (Wayland 原生) ← GTK3/GTK4 推荐
       │         │
       │         └── 合成器 (GNOME Mutter/KWin)
       │                    │
       │                    └── 输入法 (通过 ibus dbus 协议)
       │
       ├── IM 模块 (GTK_IM_MODULE / QT_IM_MODULE)
       │         │
       │         └── 直接通信 → 输入法
       │
       └── XMODIFIERS (XWayland 应用)
  • GTK3/GTK4 在 Wayland 下优先使用 text-input-v3 协议
  • 设置 GTK_IM_MODULE=fcitx 会强制使用 IM 模块路径，绕过原生协议
  • 在 GNOME 下通过 GTK_IM_MODULE=fcitx 时，输入法候选框由 IM 模块自行绘制，无法获取正确的全局坐标
  • Kimpanel 扩展作为 GNOME Shell 的一部分，可以获取窗口坐标，从而正确显示候选框

参考 链接到标题