# 10.2 Fcitx 输入法框架

输入法框架与具体输入法是两个不同的技术层次，输入法运行依赖框架的支持。这种架构关系在 Windows 系统中同样存在，可参见 Microsoft. TSF 管理器\[EB/OL]. \[2026-04-04]. <https://learn.microsoft.com/zh-cn/windows/win32/tsf/text-services-framework>。该文档介绍了 Windows 文本服务框架的架构与接口规范。

Fcitx 即“小企鹅输入法”，原始英文全称为“Free Chinese Input Tool of X”（X 窗口系统的自由中文输入工具）。自 Fcitx 5 起，该缩写不再对应单一全称，官方提供了多种释义（如“Flexible Context-aware Input Tool with eXtension”等），以体现 Fcitx 的发展已超越中文输入范畴。关于英文命名的历史渊源，可参见：小企鹅输入法 5. 历史\[EB/OL]. \[2026-04-16]. <https://fcitx-im.org/wiki/History/zh-cn>。该页面记录了 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 安装：

```sh
# cd /usr/ports/textproc/fcitx5/ && make install clean # 主程序
# cd /usr/ports/textproc/fcitx5-qt/ && make install clean  # 同时包含 Qt 5 和 Qt 6
# cd /usr/ports/textproc/fcitx5-gtk/ && make install clean # 同时包含 GTK 2、3、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/ # 创建自启动路径。如果使用其他用户，应在该用户的命令行下执行
$ cp /usr/local/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart/  # 设置 Fcitx 5 开机启动
```

## 配置 Fcitx 环境变量

设置好自启动后，还需配置相应环境变量，确保输入法框架在各应用程序中正常工作。

### X11

在 X11 环境下，需要根据所使用的桌面管理器及 Shell，选择合适的方式配置：

* 显示管理器配置路径

1. SDDM、LightDM、GDM 都可在 **\~/.xprofile** 文件中写入 A 组配置
2. LightDM、GDM 可在 **\~/.profile** 文件中写入 A 组配置
3. SDDM 可在用户登录 Shell 的配置文件中写入配置

* Shell 配置路径

1. sh: 在 **\~/.profile** 文件写入 A 组配置
2. bash: 在 **\~/.bash\_profile** 文件或 **\~/.profile** 文件写入 A 组配置
3. zsh: 在 **\~/.zprofile** 文件写入 A 组配置
4. csh: 在 **\~/.cshrc** 文件写入 B 组配置

> **注意**
>
> 如果登录桌面的用户账户不是 root，则无法使用 root 身份设置，必须切换到该普通用户，并在不使用 sudo 的情况下进行配置。

* A 组（sh/bash/zsh）

```ini
export LANG=zh_CN.UTF-8            # 设置系统语言为中文
export LANGUAGE=zh_CN.UTF-8       # 设置优先语言为中文
export LC_ALL=zh_CN.UTF-8         # 设置所有本地化环境变量为中文
export XMODIFIERS='@im=fcitx'    # 设置 X 输入法模块为 fcitx
export GTK_IM_MODULE=fcitx        # 设置 GTK 应用使用 fcitx 输入法
export QT_IM_MODULE=fcitx         # 设置 Qt 应用使用 fcitx 输入法
```

* B 组（csh）

```ini
setenv LANG zh_CN.UTF-8
setenv LC_ALL zh_CN.UTF-8
setenv LANGUAGE zh_CN.UTF-8
setenv XMODIFIERS @im=fcitx
setenv GTK_IM_MODULE fcitx
setenv QT_IM_MODULE fcitx
```

### Wayland

在 Wayland 下，不应设置 `GTK_IM_MODULE` 与 `QT_IM_MODULE`。Wayland 提供了输入法相关的协议（`text-input` 和 `input-method`），不依赖 GTK 和 Qt 的输入法模块也能正常使用输入法。设置 `GTK_IM_MODULE` 或 `QT_IM_MODULE` 可能适得其反，例如输入候选框与光标位置间距离异常。

运行在 XWayland 下的程序，输入法由环境变量 `XMODIFIERS='@im=fcitx'` 配置。

* A 组（sh/bash/zsh）：

```ini
export LANG=zh_CN.UTF-8            # 设置系统语言为中文
export LANGUAGE=zh_CN.UTF-8       # 设置优先语言为中文
export LC_ALL=zh_CN.UTF-8         # 设置所有本地化环境变量为中文
export XMODIFIERS='@im=fcitx'    # 设置 X 输入法模块为 fcitx
```

* B 组（csh）

```ini
setenv LANG zh_CN.UTF-8
setenv LC_ALL zh_CN.UTF-8
setenv LANGUAGE zh_CN.UTF-8
setenv XMODIFIERS @im=fcitx
```

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

## 故障排除与未竟事宜

遇到问题，请先运行 `fcitx5-diagnose` 故障诊断，但其输出仅针对 Bash 的环境变量配置。`csh` 的环境变量配置请参考上文。

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

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

```sh
$ fcitx5-diagnose
```

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


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.