FreeBSD 中文社区
搜索 K

主题

12.3 Fcitx 输入法框架 ​

输入法框架与具体输入法是两个不同的技术层次，输入法运行依赖框架的支持。

Fcitx 即“小企鹅输入法”，原始英文全称为“Free Chinese Input Toy for X”（X 窗口系统的自由中文输入玩具）。自 Fcitx 4 起，该缩写不再对应单一全称，官方提供了多种释义（如“Flexible Context-aware Input Tool with eXtension”等），以体现 Fcitx 的发展已超越中文输入范畴。

技巧

视频教程见 FreeBSD 中文社区. 006-FreeBSD 14.2 安装 fcitx5 及其输入法[EB/OL]. [2026-04-04]. https://www.bilibili.com/video/BV13ji2YLE3m.

注意

在 FreeBSD-CURRENT 中可能会出现不可预见的问题：Fcitx 5 诊断信息英文乱码，输入法出现汉字显示异常，Qt 环境下无法正常加载输入法。

12.3.1 安装 Fcitx5 ​

  • 使用 pkg 安装：
sh
# pkg install fcitx5 fcitx5-qt5 fcitx5-qt6 fcitx5-gtk2 fcitx5-gtk3 fcitx5-gtk4 fcitx5-configtool zh-fcitx5-chinese-addons
  • 或者使用 Ports 安装（fcitx5-qt 与 fcitx5-gtk 为带 FLAVOR 的 Ports，每次仅构建对应 Qt 或 GTK 主版本，必要时需分别指定 FLAVOR 构建）：
sh
# cd /usr/ports/textproc/fcitx5/ && make install clean # 主程序
# cd /usr/ports/textproc/fcitx5-qt/ && make FLAVOR=qt5 install clean  # Qt 5 支持
# cd /usr/ports/textproc/fcitx5-qt/ && make FLAVOR=qt6 install clean  # Qt 6 支持
# cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk2 install clean # GTK 2 支持
# cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk3 install clean # GTK 3 支持
# cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk4 install clean # GTK 4 支持
# cd /usr/ports/textproc/fcitx5-configtool/ && make install clean # fcitx5 的图形配置工具（基于 Qt 6/KF 6）
# cd /usr/ports/chinese/fcitx5-chinese-addons/ && make install clean # 输入法

使用 SLiM 显示管理器时，系统会提示无法找到 IBus。

12.3.1.1 Fcitx 5 开机自启动 ​

安装完成后，设置 Fcitx 5 随系统自动启动。

创建自启动路径。若为其他用户配置，应在该用户的命令行下执行：

sh
$ mkdir -p ~/.config/autostart/

设置 Fcitx 5 开机启动：

sh
$ cp /usr/local/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart/

12.3.2 配置环境变量 ​

完成自启动设置后，还需配置相应环境变量，确保输入法框架在各应用程序中正常工作。有两种方法可以实现。

12.3.2.1 X11 ​

为简体中文 UTF-8 编码设置变量，编辑 ~/.login_conf 文件，加入以下内容：

ini
me:\
	:lang=zh_CN.UTF-8:\
	:setenv=LC_ALL=zh_CN.UTF-8,GTK_IM_MODULE=fcitx,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\
	:charset=UTF-8:

编辑后，需要执行以下命令来更新登录能力数据库：

sh
$ cap_mkdb ~/.login_conf

12.3.2.2 Wayland ​

在 Wayland 下， QT_IM_MODULE 的设置取决于桌面环境：在 KDE Plasma 下应取消设置（Qt 通过 KWin 的 text-input 协议与 Fcitx 5 通信），在其他桌面环境下仍需设置为 fcitx。

在 Wayland 下，GTK_IM_MODULE 的设置需视情况而定。

Wayland 提供了输入法相关的协议（text-input 和 input-method），GTK 3/4 在 Wayland 下可使用 text-input-v3 协议与 Fcitx 5 通信，无需依赖 GTK 输入法模块。若设置了 GTK_IM_MODULE=fcitx，GTK 3/4 应用会回退到 X11 输入法模块，可能导致候选框与光标位置间距离异常。

因此，不建议设置环境变量 GTK_IM_MODULE，建议通过 GTK 配置文件指定输入法模块：

  • 在 ~/.gtkrc-2.0 中添加 gtk-im-module="fcitx"
  • 在 ~/.config/gtk-3.0/settings.ini 的 [Settings] 段中添加 gtk-im-module=fcitx
  • 在 ~/.config/gtk-4.0/settings.ini 的 [Settings] 段中添加 gtk-im-module=fcitx。

运行在 XWayland 下的程序，输入法由环境变量 XMODIFIERS='@im=fcitx' 配置。示例 ~/.login_conf 配置文件如下（以非 KDE 桌面环境为例）：

ini
me:\
	:lang=zh_CN.UTF-8:\
	:setenv=LC_ALL=zh_CN.UTF-8,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\
	:charset=UTF-8:

注意

若使用 KDE Plasma 桌面，应从上述 setenv 中移除 QT_IM_MODULE=fcitx。

编辑后，请更新登录能力数据库。

12.3.3 安装 RIME 中州韵输入法 ​

除了 Fcitx 自带的中文输入法插件外，还可以安装 RIME 中州韵输入法，这是一个高度可定制的输入法引擎。

  • 使用 pkg 安装：
sh
# pkg install zh-fcitx5-rime zh-rime-essay
  • 或者使用 Ports 安装：
sh
# cd /usr/ports/chinese/fcitx5-rime/ && make install clean
# cd /usr/ports/chinese/rime-essay/ && make install clean

注意

chinese/rime-essay 是必要的，它是 RIME 的共享词汇与语言模型，没有此 Port，RIME 输入法只会显示乱码。

如果 RIME 未自动添加到输入法列表，请手动添加以完成初始化。

普通用户如果配置未生效，请检查 Shell 是否已按教程配置。

12.3.4 参考文献 ​

12.3.5 故障排除与未竟事宜 ​

如果使用 Qt 相关桌面，请先更新基本系统及第三方软件包，再排查故障。

遇到问题，请先运行 Fcitx5 输入法诊断工具，检查配置和环境问题：

sh
$ fcitx5-diagnose

如果出现与 bash 相关的提示且无法输出诊断结果，请安装 Bash。

Fcitx 5.x 中未检测到 Fcitx Qt 4 支持模块属于正常现象。