从Fcitx4升级至Fcitx5

个人数据存放

几乎所有的fcitx4数据都存储在 ~/.config/fcitx 下。

对于fcitx5，路径更接近XDG标准， ~/.local/share/fcitx5 和 ~/.config/fcitx5 。

其中，Fcitx 4的Rime数据位于 ~/.config/fcitx/rime ， Fcitx 5的Rime数据位于 ~/.local/share/fcitx5/rime 。

安装什么软件包

发行版可能有自己的方式来拆分包，我将只讨论它们如何在源包上映射。

可以保留旧数据

您需要重新配置输入法列表，不支持迁移配置文件。

Fcitx使用技巧

fcitx输入特殊字符

快速短语

快速短语是一个内置的插件，它允许你输入一些东西来搜索和匹配通常需要更多努力才能输入的文本。

可以全局触发，默认热键 Meta + `

它有一些内置的表，可以在Github上查看，或者在本地使用quickphrase编辑器GUI（从Configtool中的quickphrase设置启动）。

内建表包括：

1. Latex，它允许你用Latex语法输入数学/其他符号。例如，“\alpha”将产生“α”。
2. 表情符号Ascii码，允许你输入以“:”为首的Unicode表情符号字符，这是你经常在即时通讯软件中看到的。例如，“：smile：”将生成😄。
3. Emoji，它包含了一个类似“考莫吉”的短语列表，例如：“微笑”是为了“（∀·）”。

快速短语也可以用Lua或C扩展。

Unicode类型

Fcitx 5还提供了一个Unicode插件，允许您使用十六进制数字输入Unicode，或使用描述进行搜索。

Ctrl + Shift + U 为您提供了与Gtk的内置Unicode特性类似的体验，您只需键入十六进制数字并按空格。如类型 Ctrl + Shift + U, 2, 6, 3, a, space 将为您提供Unicode字符☺。

或者使用 Ctrl + Shift + Alt + U ，您将能够使用description进行搜索。如果你只是按 Ctrl + Shift + Alt + U ，它会显示你的剪贴板和当前选择字符串的Unicode。

如果你想搜索描述，你只需要输入描述，例如，你可以用Unicode字符🍆搜索茄子。

用compose打字

这是老派的X11特性，但也适用于Fcitx支持的任何地方。您可以在xkbcommon文档中找到一些文件语法的描述。

它允许您将按键序列转换为任何字符串。但请注意，此功能是全局的，您不能轻易禁用它。

在键盘引擎中使用长按

当在键盘引擎中启用长按选项时，您可以获得映射到您所按的键的候选文本列表。映射是完全可定制的，并允许您在某些应用程序中禁用它。

Emoji输入

如果您正在使用布局引擎（输入法命名为“键盘-布局名称”），您可以使用快速短语搜索Unicode CLDR注释。例如，使用“键盘-英语（美国）”，您可以搜索apple的🍎和🍏。可用于搜索的语言与布局语言相关联。

您也可以使用其他方法，如快速短语内置表方法，或与Unicode插件，或撰写上述。

https://fcitx-im.org/wiki/Tips_and_Tricks

Fcitx5输入法相关环境变量

这个页面介绍了以下环境变量的含义。你不需要理解他们来使用Fcitx，但是以下内容可能会在你遇到问题是帮助你检查哪里出了问题。

XMODIFIERS

这个变量仅影响 XIM。格式为

XMODIFIERS=@im=<xim 服务器名称>

当 XIM 服务器启动时，他会注册一个应当在这里使用的名称。这个名称不能和其他 XIM 服务器相同，因此你无法在同一个 X 服务器下运行两个 Fcitx。通常情况下，Fcitx 的 XIM 服务器名称为 fcitx。

因此对于 Fcitx 来说这个设置应当为

XMODIFIERS=@im=fcitx

在非 CJK 语言环境中，如果这个环境变量没有设置，一些程序中 XIM 将无法工作，这意味这你最好总是设置了这个环境变量。并且 XIM 也需要你有正确的语言环境，这意味着你的语言必须在下面的命令的输出当中

locale -a

你可以通过以下命令检查你当前的语言环境

locale

为了使用 XIM，你的语言不能设置为 C 或者 POSIX。

GTK_IM_MODULE

这会覆盖系统的gtk输入法模块的自动选择。在默认情况下，gtk按照语言选择对应的输入法模块。Fcitx声明它支持 “zh:ja:ko:*"。这些信息将被记录在一个文件当中，在大多数的 linux 系统中，这个文件为 /etc/gtk-2.0/gtk.immodules 和 /etc/gtk-3.0/gtk.immodules，有时会以 -32 或者 -64 结尾。

在 Debian 进行了多架构的迁移之后，将使用不同的文件。对应文件将为 /usr/lib/<架构>/gtk-{2,3}.0/gtk.immodules }} 你需要使用

gtk-query-immodules-2.0 > <gtk-2.0 的输入法模块文件>

更新 gtk2 的文件，

或者如果你的 gtk2 版本新于 2.24.20，则应当使用

gtk-query-immodules-2.0 --update-cache

就像 gtk3 一样。

以及

gtk-query-immodules-3.0 --update-cache

更新 gtk3 的文件。

FCITX5输入法迁移通告

来自[email protected]发布于[email protected]的最新消息

各位好，

参照 fcitx 上游的活动记录 [1]，原有的 fcitx 4.x 输入法框架的所有仓库已于 2024年5月归档（archived）。可以看出 fcitx4 输入法框架在数年的过渡期之后 其上游的维护与支持已告停止。

考虑到上游的开发重心，以及 fcitx 4.x 对 wayland 协议因设计原因无法运行于 wayland 环境下的情况，我建议现有 fcitx4 用户尽早测试换用 fcitx5， 并择机从 fcitx4 迁移到 fcitx5。

考虑到开发和支持周期问题，下一个 Debian Stable (Debian 13, Trixie) 版本中 仍然会保留所有 fcitx4 的相关软件包。但随着情况的后续发展，fcitx4 的相关 软件包可能最早会在 Ubuntu 26.04 LTS 发布日期后被逐步废弃或移除。

下面是一些常见问题：

有通用的 fcitx4 -> fcitx5 迁移文档吗？

-> Debian 中可以参考 https://wiki.debian.org/I18n/Fcitx5 这份维基文档。 -> 如需阅读上游的文档，请访问 https://fcitx-im.org/wiki/Fcitx_5/zh-cn 这里。

fcitx5 相较于 fcitx4 移除了哪些输入法支持？

-> 根据 https://fcitx-im.org/wiki/Upgrade_from_Fcitx_4 ，移除的输入法大致如下：

-> fcitx-googlepinyin -> fcitx-sunpinyin -> fcitx-libpinyin -> 这三个输入法的用户应转用 fcitx5-chinese-addons。

在Wayland上使用Fcitx5

Wayland是下一代显示服务器协议。虽然该协议的初始版本是在2008 年，但对输入法的支持并不是很理想。

此外，在基于Wayland的合成器上使用输入法可能需要不同的设置才能使其工作，并且 Wayland 尚不支持在 X11 下工作的 fcitx 的某些功能。

本页将尝试涵盖所有当前信息以及一些基本细节，并且设置Fcitx5页提及的配置仍然有用。

应用程序

TL;DR 我们还需要 XMODIFIERS, GTK_IM_MODULE 和 QT_IM_MODULE?

XMODIFIERS

对于 XMODIFIERS来说我们仍需要。 在 X11 和 XWayland 下运行的 X11 应用程序几乎没有区别。

GTK_IM_MODULE

在理想的设置中，您应该使用在 X11 下运行的 fcitx im 模块 Gtk 应用程序，以及用于 wayland 的 Gtk 的 text-input-v3。执行此操作的方法是：

1. 不要设置GTK_IM_MODULE环境变量。

2. 对于 Gtk2，在 ~/.gtkrc-2.0 中添加以下内容

gtk-im-module="fcitx"

3. 对于 Gtk 3，请在 ~/.config/gtk-3.0/settings.ini中添加以下内容

[Settings]
gtk-im-module=fcitx

4. 对于 Gtk 4，请在~/.config/gtk-4.0/settings.ini中添加以下内容

[Settings]
gtk-im-module=fcitx

5. 如果您使用的是 GNOME 3+，请同时运行以下命令。

gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"

GTK_IM_MODULE，就目前而言，现代 Gtk 3/4 应用程序应该能够使用 text-input-v3，几乎所有合成器都支持它，除了 weston。在设置 GTK_IM_MODULE 的值方面，有几种不同的选项。当它被取消设置时，Gtk 内置的 Wayland im 模块将用于 Gtk3 和 Gtk4。虽然你也可以通过执行 GTK_IM_MODULE=wayland 来强制执行它，但请记住它也会被 Gtk2 接收。设置 GTK_IM_MODULE=fcitx 仍然可以工作，如果你的合成器不支持 Wayland 输入法前端，这是必要的。

Fcitx5定制主题

经典用户界面

Fcitx5有一个基于自定义的类ini配置文件和图片的简单主题引擎。它会同时在服务器侧输入法界面和fcitx5新的客户端侧输入法界面生效。在X11下，输入法的窗口由fcitx的服务器程序渲染。但是在Wayland下面，它可能会由像Qt、Gtk这样的客户端程序渲染。他们会共用相似的逻辑和大多数的特性。但是Qt是一个例外，由于在Qt下窗口由本地Qt库的API渲染，因此它不支持“由输入法语言渲染文本”选项。

经典用户界面的选项

• 竖列选词列表。启用此项，在输入法引擎没有指定的情况下，则默认会以竖列的方式显示候选词列表。但是输入法引擎逻辑也可能会覆盖这个显示方向。
• 各屏幕使用独立DPI。使用输入窗口所在屏幕的DPI缩放来渲染文字。这个选项大多数情况下只会影响X11。在X11下，Fcitx会读取配置的Xft.dpi值，并且将此值当作为您主屏幕所使用的DPI值。如果您使用的是双屏幕配置，并且主屏幕的物理DPI是120，副屏幕的是280。如果Xft.dpi值被设置为96，那么fcitx在您的主屏幕中使用的渲染DPI将会是96，另一个屏幕则按照等比例缩放使用280/120*96=224的DPI来渲染文字。
• 使用鼠标滚轮来前后翻页
• 由输入法语言来渲染文字。特性的字符在不同的语言环境下可能会使用同一个Unicode编码进行表示。此选项允许文字使用输入法语言的本地设置来显示文字。举个例子，使用像拼音等中文输入法时它会显示为中文变体的字符，使用日文输入法时的日文变体就会显示为日文变体。使用此选项要求所使用的字体支持不同地区设置。

Kim面板

这是一个基于 DBus 接口的用户界面，在输入法框架中通用。有多种实现可以用于不同的桌面环境。

• Kimpanel plasmoid, 包含在KDE Plasma5桌面环境的plasma-desktop软件包。
• GNOME扩展，可以在extensions.gnome.org中可以找到的。由 User:Weng Xuetian在github维护.
• Kimtoy, 一个第三方的独立程序。 因为Wayland和输入法之间复杂情况的问题，在非GNOME环境下使用Fcitx的输入法模块时，Kimpanel可能无法在Gtk/Qt的原生wayland程序下使用。 这主要是因为kimpanel作为 GNOME 扩展，能够获取窗口信息并自由移动窗口。 同样的情况并不适用于其他 Kimpanel 实现。 将窗口放在正确的位置比外观重要得多，因此在这种环境下不能使用 kimpanel，而是使用客户端输入面板。

设置Fcitx5

开机自启动

特定发行版中的工具

特定的发行版可能会提供一些用于自动启动 Fcitx 的工具，并且这些工具通常也会设置环境变量。

im-config (Debian/Debian-based/Ubuntu)

这是一个用于 Debian 和 Debian-based 发行版的工具。在登录到 GUI 之后，从命令行执行 im-config，应该会弹出一个向导程序，在其中选择 fcitx5 即可。

imsettings (Fedora)

这是一个与 im-config 类似的程序，它也提供了 GUI 来选择要使用的输入法框架。imsettings 应该是被默认安装的，如果没有，你可以手动安装它。imsettings 可以设置环境变量并且启动相应的输入法，它还提供了一个图形化的前端用于修改配置。你需要做的就是简单地执行im-chooser，log-out 然后再次 log-in。

针对 Fedora 36 KDE 的操作说明。 这个操作说明应该适用于除 GNOME 外的 XDG 兼容桌面。

fcitx5-autostart (Fedora)

这是一个 [fedora package]，打包了一个用于设置环境变量和 XDG autostart file 的 /etc/profile.d 脚本，可用于自启动。

XDG Autostart

特定的发行版可能没有提供这个文件，如未提供，你可以直接复制 /usr/share/applications/org.fcitx.Fcitx5.desktop 到 ~/.config/autostart

GNOME 3.6 之后的注意事项

1. libibus 可能编译为 gnome 的依赖项，不要尝试删除它。如果你正在使用 gentoo，请尝试以下步骤来删除 ibus： 在make.conf中添加-i18n使用标记，然后运行：

emerge --update --newuse --deep @world --ask

• 使用 -nls use 标志重建 gnome-shell
• 删除app-i18n/ibus:

emerge -cav app-i18n/ibus

2. 卸载系统上包含 ibus-daemon 的软件包。

或者如果你想保持 ibus 的安装（如果你想使用 fcitx，你根本不需要 ibus，对于较旧的 gnome 3.6，你也可能会遇到这个错误，所以你最好删除它），运行：

gsettings set org.gnome.settings-daemon.plugins.keyboard active false 

对当前用户生效。

Or,

3. 如果您使用的是 fedora，请确保使用 imsettings 选择 Fcitx。

4. 如果 set GTK_IM_MODULE 不起作用，请尝试运行以下命令。

gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"

重新登录。

https://fcitx-im.org/wiki/Note_for_GNOME_Later_than_3.6

Fcitx5常见问题

当你抱怨输入法无法正常工作前，请先阅读这个页面。

从 4.2.7 开始，Fcitx 提供了一个 fcitx-diagnose 的命令，它可以检测一些常见的问题并且给出一些建议。

使用 Ctrl + Space 时无法激活 Fcitx

检查你要输入文字的应用程序。

Wayland

参考 在Wayland 上使用 fcitx5。

这是唯一一个有问题的程序吗？

最可能的原因是某个快捷键占用了 Ctrl Space，请修改另一个快捷键并重试。这常见于编辑器中，因为很多集成开发环境默认使用 Ctrl+Space 作为补全的快捷键。

所有 Gtk 程序都有问题？

• 请打开一个传统意义上的Gtk程序（所谓传统，就是它不应该是Firefox，Libreoffice这种仅仅是是使用Gtk样式作为界面的程序）。Gedit是一个不错的选择。右键点击输入框，将会弹出一个“输入法”菜单，请确认“Fcitx”被选中。
• 如果菜单中确实有Fcitx，但是还是无法正常工作，请先尝试重新启动Fcitx，如果这次就可以工作了，那么请检查你的DBus设置，或者延长Fcitx的启动时间。如果你使用自定义的启动脚本，你可以参考配置 (其他)
• 如果Fcitx没有默认选中，那么请先尝试选中它，并且立刻试试可否输入。如果不行，请参见上面一条。为了永久性的修复这个问题（默认选中 Fcitx ），请阅读安装和配置中的配置部分。 如果没有 Fcitx这项，那么请首先检查你的安装，你所需要的包名包含了fcitx和gtk。如果你是从源码编译的Fcitx，请确认你启用了GTK2，GTK3的输入法模块选项。如果你确认这点的话，请阅读输入法相关的环境变量中的如何更新Gtk的缓存文件。 如果你正在使用 Ubuntu，并且刚刚升级到 12.04，或者发生了什么不好的事情 (由于打包者的疏忽，或者有问题的包管理器无法按照正确顺序更新包，例如 pacman) 你可能会注意到 gtk.immodules 相关的文件并未在升级时正确生成。试试卸载fcitx-frontend-gtk2, fcitx-frontend-gtk3 或者你发行版对应的包，然后重新安装这两个包来触发文件的生成。然后重新检查输入法菜单里面是否有“Fcitx”。

所有Qt程序都有问题？

• 运行qtconfig (名称可能根据你的发行版有所不同，他可能是 qtconfig-qt4 )，选择第三个标签，确认fcitx是在默认输入法组合框中。如果没有，请检查你的安装。
• 以上解决方案也可以类似解决XIM的问题，但我们强烈建议你使用输入法模块。参见输入法相关环境变量。

Telegram Desktop

一些发行版的telegram desktop使用了qt6。这时候要确保系统上安装了Qt6的输入法模块。（对于fcitx4而言，在archlinux上要安装fcitx-qt6软件包）

Chromium或者任何基于chromium的浏览器（例如，Microsoft Edge）

对于在 X11 下运行的 Chromium，如果使用没有设置 DBUS_SESSION_BUS_ADDRESS 选项的 startx 启动图形用户界面，可能会遇到 这个问题，它会导致基于 Chromium 的浏览器无法正确使用 dbus。为了解决这种情况，可以这么做：

1. 在 ~/.xinitrc 中自己导出 DBUS_SESSION_BUS_ADDRESS（或者如果您使用的是基于 debian 的系统，则更改为使用 ~/.xsession）。
2. 或者使用像sddm、gdm、lightdm这样的显示管理器替代startx。

对于在 wayland 下原生运行的 Chromium，唯一支持的原生 wayland 输入法协议是text-input-v1，只有 weston 支持。或者，也可以使用 Gtk4 的 im 模块，需要使用以下标志 (—enable-features=UseOzonePlatform –ozone-platform=wayland –gtk-version=4) 来使其启用 Gtk im 模块，但是除非使用 kimpanel + GNOME，否则在光标位置弹出候选词窗口的功能就完全坏掉了。

安装Fcitx5

Fcitx 软件包通常包括两部分部分：主程序，作为应用程序的输入法模块和插件（通常它们都是输入法引擎）。

从Linux发行版安装Fcitx 5

您需要从自己的软件包列表中搜索指定的Fcitx包。Fcitx 5软件包的名称中通常包含“fcitx5”。

截至今天，除了一些滚动发行版，fcitx5尚未在发行版存储库中普遍可用。

下面是一些在您使用的发行版中搜索 Fcitx5 软件包的示例。 您还可以使用桌面提供的 GUI 软件中心，例如 gnome-software（GNOME）或Plasma-discover（KDE）发现。

yum search fcitx5 # CentOS
dnf search fcitx5 # Fedora
pacman -Ss fcitx5 # Archlinux
zypper search fcitx5 # OpenSUSE
apt-cache search fcitx5 # Debian/Ubuntu

或者pkgs.org提供一个在不同发行版中搜索软件包的简单方法。 请注意可能有一些版本为0.0～git这样的包，这种版本是一些相当老的版本，比最老的Fcitx5稳定发布版本还要老。通常不建议使用这种版本的Fcitx5.

pkgs.org 也会提供针对不同发行版的特定安装命令。

一个基本的fcitx5安装包括：

• fcitx5, 主程序
• fcitx5-gtk, fcitx5-qt, 针对最受欢迎的几种UI开发工具包的输入法模块。
• fcitx5-configtool, GUI配置程序。
• 对于不同语言，有许多的输入法引擎

一些额外的插件和主题支持：

• fcitx5-lua, 提供lua脚本支持
• fcitx5-material-color, 一个Fcitx5漂亮主题的合集

从Flatpak安装Fcitx5

Flatpak 是一个用于Linux系统的软件分发和包管理工具软件。有两个flatpak仓库提供了fcitx5软件包，一个是flathub，另一个是fcitx本身的不稳定仓库。

截止今日，我们仍然在向flathub推送fcitx5软件包。flathub上现在仅仅只有fcitx5主程序，中文输入法，注音输入法，以及Mozc输入法。

您需要先对flatpak的软件仓库进行配置，可以通过执行下面的命令，或者在图形界面软件上操作完成。

# 添加 flatub 仓库, fcitx5-unstable 也会依赖一些这个仓库中的运行时软件包。
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
# 可选部分: 如果你想要使用不稳定版本的fcitx5，也可以添加 fcitx5 非稳定仓库。
flatpak remote-add --user --if-not-exists fcitx5-unstable https://flatpak.fcitx-im.org/unstable-repo/fcitx5-unstable.flatpakrepo

从flatpak安装fcitx