2175 字
11 分钟
【DotFile】如何优雅地配置使用Fcitx5——一文搞懂如何配置fcitx5环境变量
2026-05-26
DotFile
Fcitx5
/
DotFile

背景#

TIP

官方文档：https://fcitx-im.org/wiki/Fcitx_5

在Linux上进行高效的中文输入是每个Linux新手进入Linux社区的第一个挑战（前提你不是通过Arch入门Linux的）。在众多的输入法引擎中，Fcitx5凭借着原生Wayland支持，较低的内存占用，流畅的输入体验，成为了许多Linux用户的首选。

这里我以Fedora为例，说明如何在Linux上优雅地配置使用Fcitx，包括如何如何配置Electron，Flatpak应用，以及如何在Wayland上得到更好的输入体验。

如果你只是想知道如何配置Electron应用，且又恰好使用Hyprland作为DE，我推荐你参考下面这篇博客 【踩坑】在Wayland桌面使用Fcitx5在QQ,微信中输入中文

安装Fcitx5#

大多数发行版都在自己的仓库中添加了Fcitx5本体，配置工具，以及中文输入引擎。，通过以下命令可以进行安装：

Terminal window
# CentOS
sudo yum install fcitx5 fcitx5-configtool fcitx5-chinese-addons
# Fedora
sudo dnf install fcitx5 fcitx5-configtool fcitx5-chinese-addons
# Archlinux
sudo pacman -Sy fcitx5 fcitx5-configtool fcitx5-chinese-addons
# Debian/Ubuntu
sudo apt-get install fcitx5 fcitx5-configtool fcitx5-chinese-addons

针对不同的桌面环境，可能需要安装不同的支持，这里推荐都安装：

  • fcitx5-gtk
  • fcitx5-qt

系统环境设置#

这部分就是踩坑的重灾区了，大多数问题人碰到的问题基本上都来自与这里。因为不同环境开发都有各自的环境封装方法，不同的封装方法又可能导致不同的DBus（Linux进程间通信）通信协议，导致输入法连接不上也好，渲染奇怪也好，总会在这里出现问题。这里分为几个模块来说。

自启动#

特定的发行版可能会提供一些用于自动启动 Fcitx 的工具，并且这些工具通常也会设置环境变量。例如Debian/ubuntu系的im-config，只需要在im-config中选择了fcitx作为输入后端，重新登录之后基本上都能正常启动。

对与KDE桌面来着，fcitx5的自启动被加载到KWin中，只需要确保在KWin管理窗口中添加fcitx5即可。

其他的DE,如平铺式窗口管理器，基本上都需要在各自的配置文件中，添加启动项即可。

  • Hyprland中，可以在$XDG_CONFIG_HOME/hypr/hyprland.conf下添加一行命令即可：
exec-once = fcitx5

就在我写这里的时候，Hyprland v0.54+已经将默认的配置文件更改为了$XDG_CONFIG_HOME/hypr/hyprland.lua，上述的语法可能已经不使用了。 居然又改了吗，看来放弃使用Hyprland是个明智的选择，如果你使用arch+Hyprland，那你可能就得把精力放到如何去维护自己的配置上，而不是开发上了

  • niri中，可以在$XDG_CONFIG_HOME/niri/config.kdl中添加如下命令：
spawn-at-startup "fcitx5" "-d"

系统环境变量#

系统环境设置主要要看所有和窗口管理器直接通信的应用，例如记事本，终端等等。这部分只要注意系统的DE就可以解决。除此之外呢，就是配置文件加载的顺序问题了。

先说配置文件的加载顺序问题。

如果你使用Bash作为你的登录shell，~/.bash_profile 则是一个很好的用户级环境变量配置。它受到不同 DM 的广泛支持，即使你从 TTY 启动界面，它也可以工作。如果你不使用 bash，可能就得仔细检查你的 shell 配置文件是否可以用作设置环境变量的位置。

同理，在平铺式DE中，你也可以在其配置文件中加载你的配置，如niri中，你可以在$XDG_CONFIG_HOME/niri/config.kdl合适的位置添加：

environment {
  QT_IM_MODULE "fcitx"
  XMODIFIERS "@im=fcitx"
}

输入协议关注的变量主要就是三个变量：XMODIFIERS，GTK_IM_MODULE 和QT_IM_MODULE。

也就是说使用什么环境变量，取决于你使用什么样的窗口协议（X11, Wayland还是XWayland）分别指定不同ui工具开发的软件使用什么进行协议进行输入。

TIP

你可以使用fcitx5-diagnose查看当前fcitx5的环境变量问题

GTK_IM_MODULE#

在理想的情况下，你应该在 X11 下运行的 GTK 程序用 im-module，而在纯 Wayland 程序中用 GTK 的 text-input-v3 支持。其方法是：

  1. 不要设置 GTK_IM_MODULE 环境变量！
  2. 对于 Gtk2，向 ~/.gtkrc-2.0 添加如下内容：
gtk-im-module="fcitx"
  1. 对于 Gtk3，向 ~/.config/gtk-3.0/settings.ini 添加如下内容：
[Settings]
gtk-im-module=fcitx
  1. 对于 Gtk4。向 ~/.config/gtk-4.0/settings.ini 添加如下内容：
[Settings]
gtk-im-module=fcitx
  1. 如果你在用 GNOME 3 和以上版本，你还需要运行以下命令：
Terminal window
gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"

关于 GTK_IM_MODULE 环境变量，目前现代 Gtk3/4 应用程序应当能够使用 text-input-v3 协议（该协议已被绝大多数合成器支持，Weston 除外）。不设置 GTK_IM_MODULE 的时候，Gtk3/Gtk4 就会自动启用内置的 Wayland 输入法模块。虽然你也可以显式指定 GTK_IM_MODULE=wayland，但是 Gtk2 程序也会读取这个环境变量，导致兼容问题。设置 GTK_IM_MODULE=fcitx 依然是可以工作的，而且如果你使用的合成器不兼容 Wayland 输入法协议，这也是你的唯一选择。

你可以在 Gtk 的配置文件里强制使用某个 IM Module，所以就算你不设置 GTK_IM_MODULE 环境变量也仍然是可以用不同的 IM Module 的。

根据 Gtk 的实现，优先级顺序如下：

  • X11
    • 环境变量中的 GTK_IM_MODULE
    • XSettings 中 Gtk/IMModule 的值
    • 配置文件中的值
    • 基于区域设置的自动选择
  • Wayland
    • 环境变量中的 GTK_IM_MODULE
    • “wayland”

QT_IM_MODULE#

目前，QT_IM_MODULE 只能使用其自身的 text-input-v{2,4}，而该模块仅受 KWin 支持。这意味着，在 KDE 环境下，你应该取消设置该参数；但在其他桌面环境下，你需要将其设置为 QT_IM_MODULE=fcitx。此外，市面上存在的 Qt 专有应用程序也使情况更加复杂。有些应用程序不支持 Wayland，有些则没有捆绑/提供 Qt Wayland。大多数应用程序没有捆绑 fcitx 输入模块，因为 fcitx 只是 Qt 的第三方应用程序，但我注意到有些应用程序虽然捆绑了 fcitx，但并未包含所有必需的库。虽然 fcitx 5 支持 ibus 协议，但有些应用程序甚至没有捆绑 ibus 输入模块。你可以尝试一些不同的环境变量来处理这些 Qt 专有应用程序（例如 WPS、Anki、DaVinci Resolve、Mathematica 等）。

在 Qt 6.7 中，新增了一个名为“QT_IM_MODULES”的环境变量，允许您指定 im 模块的回退顺序。您可以将其设置为：

QT_IM_MODULES="wayland;fcitx;ibus"

上述的配置只是告诉了我们应该在什么条件下设置什么样的GTK_IM_MODULE和QT_IM_MODULE实际上这还与所运行的程序以那种窗口通信协议有关。

在 XWayland 下运行的传统 X11 应用程序#

对于特定应用的特定环境设置#

基于某些框架开发，或者通过沙盒执行的程序，其环境变量与系统定义的变量有所差异，这里列举几种类型：

  • Electron / Chromium
  • flatpak

Electron / Chromium 应用的兼容性#

fcitx是原生支持Electron应用的，但其默认是走X11通信协议，若系统是运行在Wayland环境下的，则会走XWayland协议，此时需要读取GTK_IM_MODULE和QT_IM_MODULE环境变量，这会导致冲突，因此需要运行程序之前，强制Electron应用走Wayland通信协议，如：

Terminal window
# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

或者

Terminal window
# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

或者

Terminal window
# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime
NOTE

在该死的微信中，除了要设置强制使用原生wayland，还需要设置wayland环境变量，但效果仍然不如人意：

  • 启动后缀
--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --gtk4 --force-device-scale-factor=1.5
  • 环境设置
Terminal window
GTK_IM_MODULE=fcitx QT_IM_MODULE=fcitx XMODIFIERS=@im=fcitx

Flatpak沙盒环境#

在沙盒环境中，因为其环境变量与系统外是隔离的，因此可能会缺少输入法的环境变量。好在Flatpak可以对但个应用设置环境变量，可以达到我们需要的效果。这里以Obsidian为例：

Terminal window
flatpak override --user \
    --env=XMODIFIERS=@im=fcitx \
    --filesystem=xdg-config/fcitx5:ro \
    md.obsidian.Obsidian
  • --env=XMODIFIERS=@im=fcitx：让 Obsidian 连接 fcitx5 输入法服务。
  • --filesystem=xdg-config/fcitx5:ro：授予 Obsidian 只读 权限访问 ~/.config/fcitx5，以便正确加载皮肤和配置。
  • 不需要额外设置 GTK_IM_MODULE 或 QT_IM_MODULE（它们的值应为空），否则会干扰原生 Wayland 应用的正常工作。

除此之外，推荐设置强制在原生wayland下运行，不然会出现XWayland与Wayland下fcitx皮肤渲染DPI不一致的问题

Terminal window
flatpak override --user --socket=wayland --nosocket=x11 md.obsidian.Obsidian
TIP

可以通过如下命令查看当前flatpak设置的环境变量：

Terminal window
flatpak override --user --show md.obsidian.Obsidian

如下命令可以取消设置的环境变量

Terminal window
systemctl --user unset-environment GTK_IM_MODULE QT_IM_MODULE
【DotFile】如何优雅地配置使用Fcitx5——一文搞懂如何配置fcitx5环境变量
http://onemom.top/posts/fcitx5_full/
作者
onemotre
发布于
2026-05-26
许可协议
CC BY-NC-SA 4.0
【ROS】ROS+Docker：分离工作系统与ROS版本紧耦合
© 2026 onemotre. All Rights Reserved. / RSS
备案徽标
贵公网安备52011502009877号