> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/di-15-zhang-ben-di-hua-yu-shu-ru-fa/di-15.3-jie-fcitx-shu-ru-fa-kuang-jia.md).

# 15.3 Fcitx 输入法框架

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

Fcitx 即“小企鹅输入法”，原始英文全称为“Free Chinese Input Toy of 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 安装：

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

### Fcitx 5 开机启动

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

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

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

设置 Fcitx 5 开机启动：

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

> **注意**
>
> 若使用 KDE Plasma (Wayland) 桌面，参见 KDE 相关章节。

## 配置环境变量

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

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

### Wayland

在 Wayland 桌面环境中，推荐同时设置 `QT_IM_MODULES="wayland;fcitx"` 和 `QT_IM_MODULE=fcitx`，这一配置在 X11 桌面上也不会导致问题；`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** 配置文件如下：

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

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

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

## 参考文献

* 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 输入法诊断工具，检查配置和环境问题：

```sh
$ fcitx5-diagnose
```

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/di-15-zhang-ben-di-hua-yu-shu-ru-fa/di-15.3-jie-fcitx-shu-ru-fa-kuang-jia.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.