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 环境下无法正常加载输入法。

安装 Fcitx5

使用 pkg 安装：

# 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 构建）：

# 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。

Fcitx 5 开机自启动

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

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

$ mkdir -p ~/.config/autostart/

设置 Fcitx 5 开机启动：

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

配置环境变量

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

X11

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

me:\
	:lang=zh_CN.UTF-8:\
	:setenv=LC_ALL=zh_CN.UTF-8,LC_COLLATE=zh_CN.UTF-8,LC_CTYPE=zh_CN.UTF-8,LC_MESSAGES=zh_CN.UTF-8,LC_MONETARY=zh_CN.UTF-8,LC_NUMERIC=zh_CN.UTF-8,LC_TIME=zh_CN.UTF-8,GTK_IM_MODULE=fcitx,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\
	:charset=UTF-8:

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

$ cap_mkdb ~/.login_conf

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 桌面环境为例）：

me:\
	:lang=zh_CN.UTF-8:\
	:setenv=LC_ALL=zh_CN.UTF-8,LC_COLLATE=zh_CN.UTF-8,LC_CTYPE=zh_CN.UTF-8,LC_MESSAGES=zh_CN.UTF-8,LC_MONETARY=zh_CN.UTF-8,LC_NUMERIC=zh_CN.UTF-8,LC_TIME=zh_CN.UTF-8,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\
	:charset=UTF-8:

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

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

安装 RIME 中州韵输入法

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

使用 pkg 安装：

# pkg install zh-fcitx5-rime zh-rime-essay

或者使用 Ports 安装：

# 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 是否已按教程配置。

参考文献

Microsoft. TSF 管理器[EB/OL]. [2026-04-04]. https://learn.microsoft.com/zh-cn/windows/win32/tsf/text-services-framework。这种输入法架构关系在 Windows 系统中同样存在，该文档介绍了 Windows 文本服务框架的架构与接口规范。
小企鹅输入法 5. 历史[EB/OL]. [2026-04-16]. https://fcitx-im.org/wiki/History/zh-cn。该页面记录了 Fcitx 从创始至今的发展历程及名称演变。
Fcitx. Using Fcitx 5 on Wayland[EB/OL]. [2026-06-05]. https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland。该页面详细说明了 Fcitx 5 在 Wayland 环境下的环境变量配置策略。

故障排除与未竟事宜

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

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

$ fcitx5-diagnose

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

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

上一页12.2 特定语言的区域配置下一页12.4 IBus 输入法框架

最后更新于 21小时前