1. 中文输入法安装在 Ubuntu 26.04 上到底在装什么

Ubuntu 26.04 中文输入法安装这件事，说难不难，说简单也不简单。我见过太多人卡在一个光标闪啊闪、打不出一个汉字的界面上，然后开始怀疑系统、怀疑键盘、怀疑人生。其实绝大部分问题都出在没搞清楚自己在装什么。这次装输入法我前后折腾了小半天，把能踩的坑基本都踩了一遍，这里把过程、原理和排查方法完整记下来，你要是刚装完系统正准备打字写文档，或者刚切到 Linux 桌面还在适应期，这篇文章可以直接抄作业。

先把最基本的问题说清楚：Ubuntu 26.04 装中文输入法，装的其实是两样东西——输入法框架和输入法引擎。框架负责和应用打交道、画出候选框、处理切换快捷键；引擎负责把拼音变成汉字、把五笔字根变成字。这两层东西组合起来才等于你键盘上那个能用中文打字的状态。很多人装完fcitx5发现打不出中文，就是因为他只装了框架，没装引擎，或者装了引擎却没在框架里启用。

为什么要专门写一篇？因为 Ubuntu 26.04 这个版本上新东西不少：默认桌面会话是 Wayland，GNOME 版本较新，输入法协议的支持情况和几年前 X11 时代完全不是一回事。你在网上搜到的那些“改一下.xprofile就好了”的老帖子，在这个版本上大概率是无效的。所以我把它当一次完整的工程实践来写，从选型到落地再到排障，每一步都说清楚为什么这么做。

2. 架构选型：为什么这次我选 Fcitx5 而不是系统自带的 IBus

2.1 输入法框架和输入法引擎是两层东西

打个比方，输入法框架像是家门口的门卫，它决定了谁能进来、进来之后往哪儿走；输入法引擎像是翻译官，负责把你说的话翻译成对方能听懂的语言。安装的时候，你必须先有门卫，再往里安排翻译官。这两者在 Linux 桌面里是拆开的两个软件包。

对 Ubuntu 来说，框架主要有三个：IBus、Fcitx5、Uim。IBus 是 GNOME 官方倾向的方案，系统装好之后它默认就在那里跑着；Fcitx5 是后起之秀，功能更细、扩展更多、候选框更好看；Uim 现在用得很少，基本可以忽略。引擎那一侧的选择就更多了，拼音、双拼、五笔、仓颉、注音、Rime 系列，各有各的适用人群。

这里有个特别容易混淆的地方：Rime（中州韵）不是输入法框架，它是一个输入法引擎。你在 Fcitx5 里可以挂 Rime，在 IBus 里也可以挂 Rime，两者的配置目录、切换方式、候选框表现都不一样。搞清这一点，后面看文档才不会迷路。

我在动手之前的判断逻辑是这样的：先确认自己需要哪些输入方式。如果只是打简体拼音，偶尔需要中英混输，那 IBus 加智能拼音其实够用；如果你要打繁体、要双拼、想自定义字库短语、想调整候选词排序逻辑，那 Fcitx5 加 Rime 更舒服。

2.2 Fcitx5 的优势体现在哪些细节上

我最终选 Fcitx5，不是因为“看起来更专业”，而是几个具体的体验差异。

第一是候选框的控制粒度。Fcitx5 的候选框可以调字号、调主题、调竖排横排、调每页候选词个数，甚至能调候选框和光标之间的距离。IBus 的候选框在 GNOME 下基本是跟着系统主题走的，你想单独换一套配色，门都没有。

第二是中国语输入法规整。Fcitx5 里有一个叫chinese-addons的包，一次性把拼音、双拼、五笔、仓颉、笔画全都装齐了，还带一个相当好用的简繁转换开关。你不需要为了换个输入方式再装一堆东西。

第三是应用兼容性。这一点在 Wayland 会话下尤其明显。Fcitx5 提供了独立的 GTK3、GTK4、Qt5、Qt6 前端模块，覆盖面广；IBus 虽然在 GNOME 下是“官方选手”，但遇到一些自己带输入法框架的软件（比如某些 Electron 应用）时，反而更容易出现“能输入但候选框飘在天上”或者“完全无法输入”的情况。

第四是诊断能力。Fcitx5 自带一个fcitx5-diagnose命令，用的是一个纯文本脚本，跑完之后会把环境变量、正在运行的前端、已加载的模块、各个应用的输入法连接状态全都列出来。出了问题之后你不需要猜，对着输出一行一行看就行。这种“可调试性”，在我这里权重很高。

当然 Fcitx5 也有它自己的麻烦，最大的一个就是它和 GNOME 的集成不像 IBus 那样天生亲和，需要你手动设置开机自启、手动登记默认框架，还要在环境变量上做文章。这部分我会在后面的实操章节里一步步说清楚。

3. 动手前的环境确认与三套方案取舍

3.1 先花两分钟摸清自己的会话类型

开装之前，有三条命令必须先跑，不然你后面的所有配置都可能打在空气上。

echo $XDG_SESSION_TYPE echo $XDG_CURRENT_DESKTOP gnome-shell --version

第一条看的是会话类型，输出wayland或者x11。第二条看桌面环境，常见输出是ubuntu:GNOME、GNOME、KDE、XFCE之类。第三条在 GNOME 下有效，输出类似GNOME Shell 48.x。

为什么这三条重要？因为环境变量的生效方式完全依赖于它们。Wayland 会话下，.xprofile不会被读取，/etc/environment和~/.config/environment.d/*.conf才是正路；X11 会话下两者都行，.xprofile读得到。如果你在一个 Wayland 会话里照着老教程改.xprofile，改完之后重启，输入法还是不出中文，然后你就开始怀疑自己是不是改错文件了——实际上是那个文件根本没被读。

我还会顺手看一眼当前的输入法框架状态：

im-config -m

这条命令会打印出当前的默认框架，未配置的时候通常会显示ibus或者一个空值。看到这个输出，你心里就有数了：系统里现在挂着的是 IBus，等下我是要替换它还是要并存，得提前定好。

3.2 三套组合的横向对比

我把常见的三种搭配整理成了下面这张表，你可以按自己的需求直接对号入座。

我自己的判断标准很简单：如果你三个月内不会去改输入法配置，选第二套；如果你希望输入法能跟着自己的用词习惯成长，长期把常用短语、专业术语都能记住，选第三套。

还有一点要提醒：三套方案里，只有第一套可以做到“装完系统就有”。另外两套都需要你主动安装软件包。这不是小差别，这意味着你要接受一次系统级的配置变更，最好先把当前配置备份一下。

3.3 一个常被忽略的前置动作：看字体

很多人装完输入法之后以为失败了，其实是字体缺了。候选框里出现的汉字变成一个个方块，或者字特别虚、特别细，这不是输入法的问题，是系统缺中文字体。

fc-list :lang=zh | head -n 20

这条命令列出系统里当前可用的中文字体。如果输出的行数很少，或者干脆没有输出，那就先补字体：

sudo apt install fonts-noto-cjk fonts-noto-cjk-extra fonts-wqy-microhei

fonts-noto-cjk是思源黑体的开源版本，字形规整，覆盖简体繁体日韩；fonts-wqy-microhei是文泉驿微米黑，体积小，在小字号下表现不错。两个都装上，候选框和终端里都不会出现方块字了。这个动作花不到两分钟，但能省掉后面一大段怀疑人生的时间。

4. 完整安装流程：从清理旧框架到候选框弹出

4.1 软件包安装与旧框架清理

先把要装的东西一次装齐。我习惯把包名写在一块儿，避免中途漏装回头再补。

sudo apt update sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5 fcitx5-frontend-qt6 fcitx5-config-qt fcitx5-material-color

这几行里的分工大致是：fcitx5是框架本体，fcitx5-chinese-addons是中文引擎集合，四个frontend包分别对应 GTK3、GTK4、Qt5、Qt6 程序，fcitx5-config-qt是图形化配置工具，fcitx5-material-color是一套挺清爽的主题。如果你的机器上跑的是 KDE，配置工具那部分可能有 KCM 版本可用，就不一定要装fcitx5-config-qt。

关于旧框架怎么处理，我踩过一次坑，这里说清楚。网上很多教程会让你把 IBus 直接卸掉，理由是两个框架同时跑会冲突。理论上没错，但实操上有风险：GNOME 桌面环境的某些组件对 IBus 有弱依赖，你一卸，可能带下来一串你不想卸的包，甚至影响桌面登录。

我现在采用的做法是“不卸，但停用”。IBus 跑在后台不会主动抢输入，只要你不把它设置成默认框架，它就不碍事。真要停，用这两条：

gsettings set org.gnome.desktop.input-sources sources "[]" ibus-daemon -drx --panel=/dev/null

第一条清空 GNOME 输入源的列表，第二条让已经在跑的 IBus 面板退出。清空输入源之后，GNOME 右上角的键盘布局指示器可能会消失，这是正常现象，因为你接下来要用 Fcitx5 的托盘图标来管理输入状态。

注意：gsettings那条命令执行之后，如果你发现系统设置里的输入源列表空了，别慌，这只是清理显示层，不影响键盘本身的英文输入。真要恢复，执行gsettings reset org.gnome.desktop.input-sources sources。

4.2 环境变量的正确写法：Wayland 和 X11 分开处理

这一步是整篇文章里最容易出错的地方，值得单拎出来讲。环境变量决定了应用该去哪找输入法框架，一旦设置错误，症状就是“某些软件能打中文，某些软件不能”，非常难排查。

在 Wayland 会话下，我推荐写到~/.config/environment.d/目录里，这个目录是被 systemd 用户实例读取的，Wayland 登录流程会走这里：

mkdir -p ~/.config/environment.d cat > ~/.config/environment.d/im.conf <<'EOF' GTK_IM_MODULE=fcitx QT_IM_MODULE=fcitx XMODIFIERS=@im=fcitx SDL_IM_MODULE=fcitx GLFW_IM_MODULE=ibus EOF

逐个解释一下这几行的用途。GTK_IM_MODULE管的是 GTK 程序，也就是 GNOME 系应用和一大堆第三方软件；QT_IM_MODULE管 Qt 程序，比如不少国产客户端和部分开发工具；XMODIFIERS是老式的 XIM 协议标识，很多老程序、Java 程序还在用它；SDL_IM_MODULE管的是用 SDL 写的游戏类程序；GLFW_IM_MODULE比较特殊，它对应的是一批用 GLFW 库写的程序，这类程序通常只认 IBus 的协议，所以这里保留ibus值，把 IBus 的那一小部分前端留作兼容用。

在纯 X11 会话下，除了上面这个文件，你还可以写入~/.xprofile，两条路都通：

cat > ~/.xprofile <<'EOF' export GTK_IM_MODULE=fcitx export QT_IM_MODULE=fcitx export XMODIFIERS=@im=fcitx export SDL_IM_MODULE=fcitx EOF

提示：系统级的/etc/environment也能写，但我不建议这么做。那个文件影响所有用户，而且格式要求很死，不加export、值不加引号，写错一个字符整个文件可能被忽略。用用户级的environment.d更保险，出问题也好回滚。

改完之后必须注销重进，环境变量才会真正生效。只重启应用不够，因为环境变量是在会话启动时读进去的。这一点和 Windows 下改完环境变量要重开命令行是一个道理。

4.3 开机自启与默认框架登记

Fcitx5 装完之后不会自动在每个会话里启动，需要登记一下。GNOME 系桌面最省事的做法是复制一份 autostart 文件：

mkdir -p ~/.config/autostart cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart/

如果你的系统里这个桌面文件的名字不太一样，可以先用ls /usr/share/applications | grep -i fcitx找一下。Ubuntu 桌面版一般就是org.fcitx.Fcitx5.desktop。

另外还要设置默认输入法框架。Ubuntu 上有个工具叫im-config，就是干这个的：

im-config -n fcitx5

这条命令会写入~/.xinputrc，把默认框架标记为 fcitx5。它同时会做一件事：把GTK_IM_MODULE之类的变量在启动脚本里预设好。如果你前面已经手写了environment.d配置文件，这两者不冲突，运行时以你先设置的那份为准。

做完这两步，注销重登，然后验证：

ps aux | grep fcitx5 fcitx5-remote -o

第一条看进程是不是起来了，正常情况下应该能看到fcitx5和一个fcitx5 --replace或者类似的进程。第二条是主动打开输入法，如果没有报错，说明框架已经接管。

4.4 首次打开配置界面：添加引擎与设置切换键

框架跑起来之后，桌面右上角（或右下角）应该会出现一个键盘样式的托盘图标。右键它，选“配置”，就打开了 Fcitx5 的设置窗口。

第一次进来会看到“当前输入法”那一栏是空的，或者只有一个“键盘 - 英语（美国）”。点左下角的加号，在弹出的列表里把“仅显示当前语言”的勾去掉，找到“中文”，展开之后应该能看到 Fcitx5 提供的一堆引擎：拼音、双拼、五笔、仓颉、注音、笔画。选你需要的那个加进去。

我个人的习惯是加三个：拼音、双拼、键盘-中文。第三个是干什么的？它是一个“中文标点模式下的英文输入”，用来在中文语境里敲变量名、路径、邮箱地址。有了它，你在写文档的时候遇到代码片段就不用反复切输入法了。

切换键的设置也在这里。默认是Ctrl + 空格，但如果你经常用 IDE，这个组合会被代码补全抢占，建议改成Super + 空格或者Ctrl + Shift + 空格。设置项在“全局选项”里的“切换输入法”那一行，点进去按一下你想要的组合就行。

候选框的调整在“附加组件”标签页里找“经典用户界面”或者“Kimpanel”，前者的配置项更全。可以调的有：字体、字号、每页候选词个数、候选框是否竖排、是否显示输入法名称。字号建议调到 16 到 18 之间，太小了带鱼屏上看不清，太大了在小窗口里会盖住内容。

折腾到这一步，正常情况下一按切换键，屏幕上应该会弹出一个小框，输入拼音就能看到汉字候选了。如果到这一步还是不行，别急，下面的排查章节基本能覆盖到。

5. 让候选词好用起来：Rime 引擎的配置实操

5.1 Rime 的目录结构和配置逻辑

如果你只用chinese-addons里自带的拼音，第五章可以跳过。但既然都折腾到这了，我强烈建议试试 Rime。它的核心价值在于：输入法会记住你的用词习惯，用得越久越顺手。

先装包：

sudo apt install fcitx5-rime librime-data

装完之后重启 Fcitx5，在配置界面里添加“中州韵”这个引擎。第一次切换过去，它会自动在用户目录里生成一套配置骨架，位置在：

~/.local/share/fcitx5/rime/

这个目录里有几个文件你需要知道它们的角色。default.yaml是全局配置，管方案列表、快捷键、候选词数量；*.schema.yaml是各个具体方案的配置，比如拼音方案、双拼方案；user.yaml和*.userdb/是你的个人词库和用词记录；installation.yaml记录安装信息。

Rime 的配置逻辑和一般软件不太一样：你不应该直接改default.yaml和*.schema.yaml，因为方案升级时会被覆盖。正确的做法是同目录下建一个default.custom.yaml和xxx.custom.yaml，在里面写“补丁”。这是 Rime 独有的机制，也是新手最容易迷惑的地方。

补丁文件的写法大致是这样：

patch: "menu/page_size": 9 "switcher/hotkeys": - "Control+grave"

这里的意思是：把每页候选词数量改成 9 个，把方案切换的热键改成Ctrl + 反引号。改完之后需要重新部署才能生效——右键托盘图标，选“重新部署”，或者用命令：

rm -rf ~/.local/share/fcitx5/rime/build

删掉编译缓存之后再触发一次输入，Rime 会自动重建。我一般两个都做，先删缓存再重新部署，双重保险。

5.2 换一套整句拼音方案

Rime 自带的默认方案叫luna_pinyin，词库偏老，整句输入的准确度放在今天只能算中等。社区里有一些维护得更积极的方案，词库更新频繁、长句切分做得更好。这些方案通常以压缩包或 git 仓库形式发布，下载下来之后把里面的*.yaml文件和*.dict.yaml词库文件一起放进 Rime 用户目录，然后在default.custom.yaml里把方案名加进列表：

patch: "schema_list": - schema: 你的方案标识名 - schema: luna_pinyin

方案标识名是那个 yaml 文件里schema_id字段的值，打开文件看一眼就知道。加进去之后重新部署，用Ctrl + 反引号呼出方案菜单，就能切过去了。

注意：下载第三方方案的时候，注意它要求的 Rime 版本。有些新方案用了一些较新的配置语法，在老版本 librime 上部署会直接报错，日志在~/.local/share/fcitx5/rime/目录下，一般会有明确的错误行号。

我实测下来，换方案这件事的收益比想象中大。默认方案打“今天天气不错我们出去走走吧”这种句子，经常要手动选两次；换过之后基本一次成型。这个差别在长时间写作时会累积成很大的效率差。

5.3 几项高频定制：候选词个数、模糊音、简繁切换

候选词个数前面提过了，改menu/page_size。我的建议是 7 到 9 之间。太少了要频繁翻页，太多了候选框会挡住视线，尤其在笔记本小屏幕上很明显。

模糊音对南方口音的用户特别有用。在default.custom.yaml里加一段：

patch: "speller/algebra": - derive/^([zcs])h/$1/ - derive/^([zcs])/$1h/ - derive/([aei])n$/$1ng/ - derive/([aei])ng$/$1n/

这段的意思是：允许 zh 和 z 互认、ch 和 c 互认、sh 和 s 互认，以及前后鼻音互认。加上之后，打“zongguo”也能出“中国”，打“senlin”也能出“森林”。代价是重码率会上来，候选词列表会变长，取舍看你自己的口音习惯。我自己的做法是只保留平翘舌模糊，前后鼻音不开，因为开了之后“因”和“英”这类常用字的选择成本太高。

简繁切换是 Rime 的内置能力，默认热键是Ctrl + 反引号呼出菜单后选“简繁转换”，或者直接发F4。如果你经常需要输出繁体，可以在配置里把简繁转换设成一个独立的引擎项，这样切换更顺手。

还有一个我觉得很实用但很少人提的功能：自定义短语。在~/.local/share/fcitx5/rime/下建一个custom_phrase.txt，每行一条，格式是“词 + 制表符 + 编码 + 制表符 + 权重”：

某实验室 msys 100 内部代号 ndm 100

这里我用的都是虚构代称，你把自己的常用术语、邮箱前缀、公司内部缩写写进去就行。写完之后在default.custom.yaml里挂上这个词典，重新部署之后，打对应的编码就能直接出词。我给自己的常用地址前缀和几个技术名词都做了条目，效率提升非常明显。

5.4 用户词库的备份与迁移

Rime 会默默学习你的用词，这些数据存在*.userdb目录里，是 LevelDB 格式的。如果你换机器、重装系统，把这几个目录拷走再放回新机器的同位置，重新部署之后就恢复如初了。

tar czf rime-backup.tar.gz -C ~/.local/share/fcitx5 rime

这条命令把整个 Rime 用户目录打包，包含词库、配置、方案。恢复的时候解压回去，把build目录删掉让它重建一次就行。

提示：跨大版本迁移的时候，最好先把新机器上的luna_pinyin.userdb之类删掉再解压，避免两份数据打架。Rime 对冲突的处理方式是合并，但合并出的词频排序偶尔会很奇怪。

6. 踩坑实录：五类高频问题怎么排查

6.1 候选框不跟随光标或者干脆不出现

这是 Wayland 会话下最高频的问题，症状是能打出字，但候选框固定在屏幕底部或者左上角，不跟着光标走。

先说原因：Wayland 下候选框跟随光标依赖text-input协议，而这个协议在各个桌面环境上的实现程度不一样。GNOME 的新版本在协议支持上有推进，但不同小版本的差异仍然存在。你的候选框飘在角落，说明你的应用和框架之间走的是“回退路径”，输入法框架拿不到光标坐标，只能自己在屏幕边缘画一个框。

排查按这个顺序走：

fcitx5-diagnose

这条命令的输出很长，重点看三块。第一块是“Environment”小节，确认GTK_IM_MODULE、QT_IM_MODULE、XMODIFIERS三个值是不是fcitx。第二块是“Frontends”小节，看 GTK3、GTK4、Qt5、Qt6 各个前端模块的加载状态。第三块是“Input Methods”小节，看当前活动引擎是哪个。

如果环境变量那部分显示的值不是fcitx，说明你前面写的配置没生效。这时候回头检查~/.config/environment.d/im.conf的文件权限和内容格式，特别注意不要有多余的空格或者中文标点。

如果 GTK3 前端显示Not found，说明fcitx5-frontend-gtk3这个包没装上，或者装了但版本不匹配。补装一遍再看。

还有一种情况是候选框位置固定在屏幕中央，这通常是应用把输入法的位置信息设成了零。GNOME Terminal 在 Wayland 下有这个毛病，换到 GNOME Console 或者别的终端就没问题。这类问题在应用侧，换个终端是最省事的解法。

6.2 个别应用打不出中文

这是第二高频问题，表现形式是“大部分软件正常，某几个软件里怎么按切换键都不出中文，只能打英文”。

Chromium 内核的应用（浏览器、部分客户端）是最典型的一组。它们在 Wayland 下默认可能走的是 X11 兼容层，输入法事件传不过去。可以试试带着参数启动：

--ozone-platform-hint=auto --enable-wayland-ime

这两个参数的作用是让程序明确走 Wayland 原生路径并打开输入法支持。有些程序支持在配置里写启动参数，不支持的可以改.desktop文件里的Exec行。

Electron 应用的情况类似但更麻烦，因为它内部的输入法处理和 Chromium 不完全一致。实践中，我遇到过的处理办法有两种：一种是加同样的启动参数，另一种是强制它走 X11 模式（--ozone-platform=x11），代价是高分屏缩放可能不完美。两种都试一下，哪个能用用哪个。

终端类应用里，前面说的 GNOME Terminal 是重灾区，老版本的 Konsole 也可能有问题。另外用 Java 写的程序（一些 IDE 和工具）对XMODIFIERS比较敏感，确认这个变量存在且值正确。

还有一个隐蔽的情况：Snap 打包的应用读不到你在用户配置里写的环境变量。这类应用需要单独处理，有的支持在应用自己的配置里设置，有的需要用系统级方式注入。我一般先看这个应用有没有 deb 版，有就换掉，比折腾环境变量省心。

6.3 重启之后输入法消失了

装好能用，重启就没了，这个症状背后通常是自启没配好。

先确认自启文件在不在：

ls ~/.config/autostart/ | grep -i fcitx

如果什么都没有，回到 4.3 节把 autostart 文件复制一遍。如果文件在但输入法还是没起来，手动跑一次看报什么错：

fcitx5 --replace -d

-d是后台运行，--replace是抢占已有实例。如果前台跑的时候有错误输出，问题就明确了。常见的错误有两类：一是权限问题，~/.config/fcitx5/目录的所有者不对；二是配置损坏，某个自定义配置文件语法错误导致整体加载失败，这时候把~/.config/fcitx5/conf/整个挪走再试，能启动就说明是配置的问题，然后一个一个文件放回去定位。

对于 X11 会话，还有一个可能：~/.xprofile里的 export 语句没被执行。检查一下文件的可执行权限和是否被登录管理器读取。

6.4 其他问题速查表

我把还遇到过的一些零星问题整理成了下面这张表，按照现象、可能原因、处理动作三列排列，遇到问题时可以直接对照。

再补一个排查思路上的经验。遇到说不清的问题，先做一次“干净环境测试”：新建一个用户账号，登录进去只配最小化的输入法，看是否正常。如果新账号正常，问题就锁定在旧账号的配置文件里；如果新账号也不正常，问题在系统层面，检查包安装和系统级配置文件。这个方法能一刀把问题切成两半，比我瞎猜快得多。

7. 升级维护与几点个人体会

7.1 版本升级前后要注意的事

Ubuntu 这种滚动式升级的发行版（版本间升级），升级过程会重装或替换一部分系统配置。我遇到过两次升级之后输入法失效的情况，两次的原因不一样：一次是environment.d里的配置文件被标记为“非标准配置文件”而提示是否保留，默认选项是覆盖；一次是im-config的设置被重置回ibus。

所以升级前的准备动作是：把~/.config/environment.d/、~/.config/fcitx5/、~/.local/share/fcitx5/rime/三个目录各打一个包放到家目录外面。升级完之后先跑fcitx5-diagnose，对比一下输出，如果框架被换回 IBus，重新执行一次im-config -n fcitx5就行。

另外，Fcitx5 在版本更新时偶尔会改配置项的字段名，老的配置项会被忽略。表现是“升级之后某些自定义设置失效了，但输入法本身能用”。这时候不要急着重装，把~/.config/fcitx5/config备份一下删掉，让程序重建一份默认的，再对照着老文件把关键项手工加回去。

还有一点值得提醒：Rime 的词库在跨大版本升级时，build目录的格式可能会变，部署时会报错。处理方式是删除build目录后重新部署，如果还报错，就把*.userdb也删掉——代价是丢失用词积累，所以前面说的备份动作在这里就体现出价值了。

7.2 我个人的几点体会

折腾了这么一圈，有几个感受比较深。

第一是“先诊断再动手”这条原则的价值。我一开始装完不出中文，第一反应是重装，结果重装了三遍还是不行。真正解决问题的是跑了一遍fcitx5-diagnose，从输出里看到GTK_IM_MODULE的值是空的，顺着这个线索才发现我的配置文件写在了错误的位置。花两分钟看诊断输出，比试错半小时有用。

第二是环境变量的写法要跟会话类型对齐。Wayland 时代，.xprofile这类老式配置文件的地位已经下降了，~/.config/environment.d/才是主流。这个变化在文档里往往一笔带过，但它是实际排查中最常见的坑。如果你在别的教程里看到改.xprofile，先确认自己的会话类型是什么，不要盲目照抄。

第三是不要追求“一键脚本”。网上有不少安装输入法的一键脚本，执行完看着什么都配好了，但你不知道它改了什么文件、放在哪里。出了问题之后你连回滚的方向都没有。我宁可手动敲十条命令，把每一条的目的搞清楚，这样下次遇到同类问题，改哪个文件心里是明白的。

最后分享一个用起来很舒服的小配置。我在 Fcitx5 里启用了“快速输入”这个附加组件，然后把自己的常用短句、邮箱地址、几个常用的代码片段都挂了进去，用一组固定前缀加几个字母就能调出来。比如输入;dz出来自己的地址，输入;log出来一段日志分析的模板。这个功能配合 Rime 的自定义短语有点重叠，但它的好处是纯图形界面配置，不用碰 yaml，适合不想折腾配置文件的场景。

这套配下来之后，我这台机器上的中文输入体验和几年前在 Linux 上打字的感受完全是两回事了。框架层选对、环境变量写对、引擎调顺，剩下的就是日常积累词库，用着用着就顺手了。