1. 别急着敲安装命令先搞懂 Ubuntu 输入法的三层结构在 Ubuntu 上装中文拼音输入法最容易犯的错是上来就sudo apt install一通装完重启然后发现——右下角托盘里那个键盘图标是灰色的或者能打字但没有候选框。这类问题九成不是包没装上而是没搞清楚输入法这三个字在 Linux 上其实是三件不同的事。我先把这件事说透后面所有的操作你都能自己推导出来而不是照着别人博客抄一遍、错一个字母就蒙了。1.1 应用、框架、引擎各管什么Ubuntu 的中文输入是一条三层的链路从上到下依次是应用层、框架层、引擎层。应用层就是你日常用的那些程序——Firefox、Chrome、VS Code、终端、WPS、微信。它们本身不实现拼音它们只负责我有一个输入框谁能给我送字。框架层就是输入法框架常见的是IBus和Fcitx5老一点的是 Fcitx4。框架的作用是常驻后台、监听键盘事件、在光标位置画出候选框、把选中的字塞进应用的输入框里。它约等于 Windows 上的输入法管理器。引擎层才是真正干活的那个拼音、双拼、五笔、仓颉、日语假名都只是挂在框架下面的一个引擎。搜狗输入法 Linux 版比较特殊——它同时打包了引擎和框架适配层所以它对框架版本有强依赖这就是后面很多坑的根源。明白这个分层之后很多现象就能直接解释了。比如英文能打、中文打不出来通常是框架起来了但没启用拼音引擎能打中文但没有候选框一般是框架和应用之间的通信通道IM module没接通重启后失效基本可以锁定环境变量没写对地方。1.2 三套主流方案的横向对比目前 Ubuntu 上跑中文拼音实际可选的路线就三条各自的特点我列成表格你可以直接对号入座。方案组成优点坑点适合谁Fcitx5 内置拼音fcitx5 fcitx5-chinese-addons官方源直接装、Wayland 支持在持续完善、词库可换、无版权顾虑默认词库偏薄需要手动导入候选框样式朴素长期用 Ubuntu 干活、追求稳定的开发者搜狗输入法 Linux 版官方 deb 包 适配层词库和联想强、和 Windows 手感接近依赖特定框架版本新旧框架共存时冲突升级系统后容易崩刚从 Windows 迁移、重度依赖云词库的人IBus 内置智能拼音ibus ibus-libpinyin系统自带、零安装候选框跟手度一般、候选词质量弱、某些应用下会丢焦点只偶尔打几个中文、不想折腾的人这张表里最关键的一行其实是第二行的坑点列。搜狗的问题从来不是装不上而是它会把旧框架作为依赖拽进来然后在某次系统升级后突然失效。我自己在两台机器上踩过完全一样的坑后面第 4 节会详细讲。1.3 我的选型结论如果这台 Ubuntu 是你要长期用来写代码、写文档的主力机我的建议非常明确用 Fcitx5 fcitx5-chinese-addons别装搜狗。理由有三个都很实际。第一是依赖干净。Fcitx5 全系列都在 Ubuntu 官方源里apt一条命令搞定不会引入任何第三方仓库将来升级系统也不会因为某个外部包卡住。第二是不会和系统打架。Ubuntu 默认预装 IBus而 Fcitx5 和 IBus 的关系是二选一只要用im-config明确指定默认框架两者可以干净共存不会互相抢键盘。第三是可折腾空间大。词库可以换、候选数量可以调、模糊音和双拼都能开、用户词库是纯文本文件可以用脚本处理——这些东西对你后期把打字体验调到接近 Windows 手感非常关键而搜狗在 Linux 上留给你的调节余地非常有限。2. 动手前的三步体检能省掉一半返工我见过太多人装完输入法发现不对劲然后反复卸载重装其实问题出在压根没做前置检查。正式安装前先花三分钟把下面三件事确认掉。2.1 先确认你的会话是 X11 还是 Wayland这是最重要的一步因为这两种显示会话下环境变量的写法、候选框的显示方式完全不同。在终端里执行echo $XDG_SESSION_TYPE输出x11说明你跑在 X11 上输出wayland就是 Wayland。Ubuntu 22.04 之后默认给的是 Wayland登录界面右下角那个齿轮里能手动切回 X11。为什么这个区别要命因为在 X11 下输入法框架通过一个叫 XIM 的老协议和应用通信环境变量必须写全而在 Wayland 下GTK 应用走的是text-input协议如果你硬把GTK_IM_MODULE设成fcitxGTK 应用反而会绕开原生协议走回退路径结果就是候选框位置乱飘甚至不显示。我的经验是先按会话类型决定变量怎么写再去装包顺序反了就要多注销好几次。2.2 确认系统版本、架构和现有框架状态顺手把这几条命令跑一遍结果记下来lsb_release -a # 确认是 22.04 还是 24.04 dpkg --print-architecture # 确认 amd64 还是 arm64 dpkg -l | grep -E fcitx|ibus # 看看已经装了什么框架 im-config -l # 列出系统认识的所有输入法框架为什么要看架构因为有些第三方 deb 包只出 amd64如果你在 ARM 的机器上比如某些开发板挂的 Ubuntu下载下来也装不上会直接报package architecture (amd64) does not match system (arm64)。为什么要看现有框架因为 Ubuntu 桌面版默认预装 IBus如果你之前手贱装过 Fcitx4那 Fcitx4 和 Fcitx5 会同时存在很多配置文件会互相覆盖导致你改了 A 文件但生效的是 B。这种问题最难查因为它不报错只是行为不符合预期。2.3 把历史残留清干净如果前面的检查发现已经有 Fcitx4 或者别的旧框架先清掉再装新的sudo apt remove --purge fcitx fcitx-bin fcitx-data fcitx-modules sudo apt autoremove --purge rm -rf ~/.config/fcitx ~/.config/fcitx5这里有个细节很多人忽略配置文件目录要手动删。apt remove --purge只清理系统级的配置家目录下的~/.config/fcitx它会原样留着。而 Fcitx5 在首次启动时如果发现同名配置目录存在会尝试读取里面的旧参数于是你看到的候选词数量、快捷键全是上一个框架的遗留值。注意删~/.config/fcitx5之前先确认里面没有你导入过的自定义词库。词库一般放在~/.local/share/fcitx5/pinyin/和配置目录是分开的删配置不影响词库但删之前顺手ls一下总没错。3. 主推路线Fcitx5 加拼音引擎的完整实操前面铺垫够了现在开始动手。这一节我会把每一步为什么这么做都讲清楚你按顺序执行就行。3.1 一次性把需要的包装齐先更新索引然后把 Fcitx5 全家桶装上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-module-cloudpinyin逐个解释一下这几个包的职责这样将来某个应用打不了字你就知道该去查哪一个。fcitx5是框架本体提供常驻进程和基础能力。fcitx5-chinese-addons是中文附加包里面包含拼音、双拼、五笔、仓颉、注音等引擎拼音就在这个包里这是核心中的核心漏了它你会得到框架在跑但没有任何中文可选的状态。后面四个frontend包是连接器负责让不同类型的应用能连上框架GTK3 对应大部分 GNOME 系应用和老版程序GTK4 对应新一点的 GNOME 应用比如 Ubuntu 24.04 上的一些原生工具Qt5 和 Qt6 对应 KDE 系应用以及大量国产软件。任何一个前端缺了就会出现浏览器能打字但某个软件不行的现象所以建议一口气全装。fcitx5-config-qt是图形配置工具不带 GUI 的话你只能用命令行调参数效率会低很多。fcitx5-module-cloudpinyin提供云拼音联想能力可选装了之后长句的准确率会有明显提升。3.2 环境变量写哪几个、写在哪这是整个流程里最容易出错的环节我拆成两半讲先确定写什么再确定写在哪。需要设置的变量一共三个GTK_IM_MODULEfcitx QT_IM_MODULEfcitx XMODIFIERSimfcitxGTK_IM_MODULE告诉 GTK 系应用去加载 Fcitx 的输入模块QT_IM_MODULE是同样的意思针对 Qt 系应用XMODIFIERS是给老的 XIM 协议用的兜底。三个缺一个对应技术栈的应用就会变成能打英文不能打中文。写在哪取决于你的会话类型场景推荐位置生效范围生效时机X11 会话/etc/environment全系统所有用户重启后X11 会话只要当前用户~/.xprofile当前用户注销重登Wayland 会话~/.config/environment.d/fcitx.conf当前用户的 systemd 会话注销重登只想临时验证终端里直接 export当前终端进程立即~/.config/environment.d/这个目录是 systemd 用户级环境变量的标准位置格式是纯KEYVALUE不要写export不要加引号。文件长这样# ~/.config/environment.d/fcitx.conf GTK_IM_MODULEfcitx QT_IM_MODULEfcitx XMODIFIERSimfcitx提示如果目录不存在mkdir -p ~/.config/environment.d先建出来。文件名必须以.conf结尾否则 systemd 会忽略它。这个坑我踩过排查了二十分钟。如果你的会话是 Wayland我实际测下来的建议是只设QT_IM_MODULE和XMODIFIERS把GTK_IM_MODULE留空。原因是 Wayland 下 GTK4 应用原生支持输入法协议强制设成fcitx会把它推回 XIM 通道候选框就会跟着窗口边缘跑而不是跟着光标跑。这个经验值在不同版本上略有差异你可以先用全量配置测一遍如果不满意再单独去掉GTK_IM_MODULE对比。3.3 用 im-config 指定默认框架环境变量写好了但系统还不知道默认输入法框架是 Fcitx5这一步必须靠im-config来做im-config -n fcitx5执行完它会往~/.xinputrc写一行配置。你可以用cat ~/.xinputrc确认一下正常输出类似run_im fcitx5为什么这一步不能省因为启动输入法进程的其实是显示管理器GDM或桌面会话的启动脚本它会读~/.xinputrc决定拉起哪个框架。环境变量只是告诉应用连哪个框架im-config才决定哪个框架被启动。两者缺一就会出现变量都对但进程没起来的诡异状态。做完这一步注销后重新登录或者干脆重启一次。别偷懒只关终端重开环境变量对已经存在的进程不生效。3.4 首次启动与基础配置重新登录后右上角应该出现一个键盘图标。点它能看到输入法菜单。如果图标没出现在终端里手动拉起看一下报错信息fcitx5 -d --replace-d是放到后台--replace是替换掉已存在的实例。如果这条命令有报错说明包没装全或者有旧框架在占位按提示缺什么补什么。接着打开图形配置界面fcitx5-configtool在输入法标签页里把左边的 Pinyin简体中文拼音添加到右边。注意别选错成 Shuangpin双拼或者 Wubi五笔除非你真的用那个。添加完之后默认的切换快捷键一般是Ctrl 空格。这里有个绕不开的坑GNOME 自己也占用了Ctrl 空格和Super 空格来切换系统输入源。如果你 GNOME 里还留着中文智能拼音这个输入源就会和 Fcitx5 抢同一个快捷键表现为按了没反应或者要按好几次才切过来。解决办法是去设置 → 键盘 → 输入源把除 English (US) 之外的全部删掉只留一个。GNOME 的输入源是给 IBus 用的Fcitx5 有自己的机制不需要在这里注册。3.5 词库、模糊音和双拼按需开装完之后你会发现默认词库偏薄打一些新词、专业术语、人名地名要一个一个字选。这时候两个东西值得配上。第一个是扩展词库。Ubuntu 源里有一个基于百科词条的拼音词库包sudo apt install fcitx5-pinyin-zhwiki装完重启框架就能用。如果源里没有这个包也可以手动下载词库文件格式是.dict丢到~/.local/share/fcitx5/pinyin/dictionaries/目录下重启生效。第二个是模糊音。南方口音的朋友对这个需求很强烈zh/z、ch/c、sh/s、n/l、前后鼻音这些都是常开的。在fcitx5-configtool的拼音设置里能找到模糊拼音开关勾选即可不需要改配置文件。至于双拼它的收益取决于你愿不愿意重新练一遍键位。我的看法是如果你每天打字量在五千字以上双拼值得投入两周适应期长期收益很明显如果只是偶尔写点东西用全拼就够了别折腾。4. 备选路线搜狗输入法的安装与共存风险前面说过我推荐 Fcitx5但确实有很多人就是习惯搜狗的联想和词库。那这一节我把搜狗这条路讲清楚包括它到底会在哪里出问题。4.1 安装步骤从官方渠道下载 Linux 版 deb 包然后sudo dpkg -i sogoupinyin_*.deb sudo apt -f install第二行是必须的因为dpkg不会自动解决依赖直接把包扔进去很可能因为缺库而处于未配置状态。apt -f install会尝试自动补上缺失的依赖。如果下载的是较新的版本它一般会自带框架适配层如果是老版本这一步可能会把 Fcitx4 作为依赖一起装进来。装完先别急着注销用下面这条命令看看拉进来了什么apt-cache rdepends fcitx 2/dev/null dpkg -l | grep -i sogou如果有 Fcitx4 相关的包被拉进来你就得做一个决定要么放弃 Fcitx5 全面转向搜狗那套要么放弃搜狗。两者共存是行不通的因为 Fcitx4 和 Fcitx5 会争抢同一个环境变量和同一个会话启动入口表现就是有时候能打有时候不能打非常难受。4.2 装完必须做的三项验收搜狗在 Ubuntu 上的验收不能只看能不能打字因为它的失效往往是渐进式的。装完重启后按这三项挨个测第一项打开 Firefox 或者 Chrome随便找个搜索框输入一段拼音。要看的不是能不能出字而是候选框是不是紧贴光标。如果候选框出现在窗口左上角或者屏幕中间说明 GTK_IM_MODULE 那条链路有问题。第二项打开 VS Code 或者终端再测一遍。这一类是 Electron 或 Qt 应用走的是另一条通道能验证 QT_IM_MODULE 是否正常。第三项重启系统再打开同样的应用测一遍。这一步专门用来验证环境变量是不是写到了能持久生效的位置。前面说过只在终端里export的话重启就没了。三项都过说明装得干净。有一项不过就按第 5 节的方法去查环境变量。5. 让配置重启不失效环境变量与自启的正确姿势这一节是所有问题的公共根因值得单独拎出来讲透。因为输入法重启后失效这个现象我在论坛上见过不下几十次答案基本都在这里。5.1 三个配置文件的生效顺序Linux 会话启动时环境变量的加载是有先后顺序的后面的会覆盖前面的/etc/environment系统级最早加载对所有用户生效。格式是纯KEYVALUE不能写export不能用$HOME这类变量展开。~/.config/environment.d/*.conf用户级由 systemd 用户管理器读取只对 systemd 管理的会话生效。~/.xprofile由显示管理器在 X11 会话启动时执行本质是个 shell 脚本可以写export也可以用变量展开。注意~/.xprofile只在 X11 会话下被读取Wayland 下这个文件根本不执行。这就是为什么有人在 X11 上配得好好的切到 Wayland 就全废了。还有一个常见的误解是~/.bashrc。很多人图省事把输入法变量写进~/.bashrc结果发现只有终端里能用图形界面的应用完全不受影响。原因很简单~/.bashrc只在交互式 shell 启动时执行GUI 应用压根不经过 shell。5.2 Wayland 下的取舍策略Wayland 这几年变化很快不同 Ubuntu 版本的行为不完全一致。我给一个实测下来比较稳的策略先按完整版配三个变量都设重启后测试。如果候选框位置正常就保持如果出现候选框乱飘、输入延迟、或者某些 GTK4 应用完全打不了字就去掉GTK_IM_MODULE只留另外两个再测。这个试两次的做法听起来不优雅但比查文档快得多因为不同发行版、不同桌面环境、不同框架版本的组合太多了没有一份文档能覆盖全部。注意改完~/.config/environment.d/下的文件后如果想不重启就验证可以执行systemctl --user daemon-reload然后注销重登。直接重启当然更保险。5.3 自启与托盘别指望它自己起来正常情况下im-config配好之后Fcitx5 会随会话自动启动。但如果发现每次登录都要手动敲fcitx5 -d说明自启链路断了。这时有两个补救办法。一是检查~/.xinputrc内容对不对必要时重新执行im-config -n fcitx5。二是直接用桌面环境的自启功能兜底在启动应用程序里新增一项命令填fcitx5 -d。这个办法简单粗暴但极其有效代价是启动会比原生方式晚一两秒刚开始那几秒打字可能还是英文。至于托盘图标如果菜单里显示成了灰色的禁用状态点一下启用就行。有时候升级后图标会变成问号或者干脆消失一般是图标主题缺了对应资源装个fcitx5-material-color之类的主题包就能恢复。6. 故障排查实录那些让我查了半天的坑前面是怎么装这一节是装完不对怎么查。我把这几年遇到过的典型案例整理出来每个都附上排查路径。6.1 能打英文中文候选框不出现这是最高频的问题。排查顺序应该是这样的先确认拼音引擎加了没有fcitx5-configtool里看输入法列表再确认框架进程在不在ps aux | grep fcitx5最后才是环境变量。如果引擎在、进程在那就是应用侧连不上。此时最有效的工具是fcitx5-diagnose这条命令会输出一大段信息包括当前会话类型、各个环境变量的实际值、各个前端模块的安装状态、甚至能检测出常见的配置错误。它会直接把可疑项标出来比如GTK_IM_MODULE 设置为 xim建议修改为 fcitx这种照着改就行。老实说学会用这个命令之后我排查输入法问题的时间至少缩短了一半。6.2 特定应用打不了字不同的应用走不同的输入通道所以只有某个软件不行这个现象指向性非常明确现象大概率原因处理方式只有 Chromium 系浏览器不行启动时未加载 GTK 输入模块确认GTK_IM_MODULE已设置并从桌面图标启动而非命令行只有 VS Code 等 Electron 应用不行走了 XWayland 且 XIM 配置缺失确认XMODIFIERSimfcitx或把 VS Code 切到 Wayland 原生模式只有 Qt 程序如 WPS不行fcitx5-frontend-qt5未安装补装对应前端包并注销重登输入时延极高、偶尔丢字云拼音网络请求超时在拼音设置里关掉云拼音试试候选框出现在屏幕角落Wayland 下强制走了 XIM去掉GTK_IM_MODULE让应用走原生协议这张表我建议存下来因为 Ubuntu 换版本的时候这些问题会以新的形式重现但排查逻辑是不变的先定位是哪个通道断了再补对应的包或变量。6.3 虚拟机和 WSL 里的额外坑如果你是在 VMware 或 VirtualBox 里跑 Ubuntu有一个宿主和客户机抢快捷键的问题。你在虚拟机里按Ctrl 空格结果宿主机先响应了或者虚拟机软件把组合键当成了自己的功能键。解决办法是在虚拟机软件的快捷键设置里把相关的组合键改成发送到客户机或者简单点——退出虚拟机的鼠标键盘独占模式让按键直接穿透进去。至于 WSL 场景我的建议是别在 WSL 里折腾输入法。WSLg 的图形层要经过一层协议转换输入法框架在里面跑起来本身就别扭字体渲染和候选框位置也都是额外变量。更实用的做法是把界面留在 Windows 侧——用 VS Code 的远程连接功能连到 WSL 里写代码输入法用 Windows 自带的零配置零风险。这个组合我用了一年多稳定性比在 WSL 里硬装输入法高出一个量级。6.4 常见问题速查表把上面的内容压缩成一张可以直接贴在手边的表症状第一条命令重点关注完全没反应ps aux | grep fcitx5进程是否存在有进程无候选fcitx5-diagnose环境变量与前端包重启后失效cat ~/.xinputrc默认框架是否正确快捷键冲突检查 GNOME 输入源设置是否残留 IBus 输入源某应用单独失效dpkg -l | grep frontend对应前端包是否安装候选词太少看词库目录是否装了扩展词库7. 把打字体验调到接近 Windows 的手感装好能用只是及格线真正舒服还需要一点调优。这一节讲几个投入产出比很高的调整。7.1 词频学习和用户词库Fcitx5 的拼音引擎会记录你的选词习惯存在~/.local/share/fcitx5/pinyin/user.dict。这个文件是二进制的不要用文本编辑器打开但可以直接复制备份。换机器的时候把它拷过去新机器第一天就有你的用词习惯这个体验提升非常明显。有个小技巧值得试如果你经常输入固定的专业术语或者公司内部名词可以在配置里把用户词频优先打开然后连续选几次正确的词一般三五次之后它会把这个词排到候选第一位。比手动造词省事得多。7.2 候选数量、字体和渲染默认候选数量是 5 个我一般调到 7。为什么不是越多越好因为候选框太宽会遮挡输入框上方的界面内容尤其是在小屏幕笔记本上。7 个是我用 14 寸屏幕试出来的平衡点超过这个数就开始影响阅读了。字体方面如果你觉得候选框里的字发虚八成是字体渲染的问题而不是输入法的问题。可以在主题设置里换成系统里已经调好渲染的中文字体会比默认字体清晰不少。7.3 配置目录的备份与迁移整个输入法的个性化配置集中在两个目录~/.config/fcitx5/配置文件包括快捷键、主题、引擎开关~/.local/share/fcitx5/词库、用户数据换电脑或者重装系统之前把这两个目录打包存一份新机器上装完框架之后直接覆盖回去重启就是原来的手感。这个操作我在做系统重装的时候基本是标配五分钟能省掉大半小时的重新配置。最后分享一个小细节。我习惯在装修完之后跑一遍fcitx5-diagnose ~/input-method-report.txt把当时的完整状态存一份。等哪天出问题了拿现在的结果和当时那份对比差异项基本就是问题所在。这个习惯是从排查网络问题时学来的用在输入法上一样好使——毕竟很多时候以前好好的现在不行了答案就藏在变化里。
Ubuntu中文输入法：Fcitx5安装配置与故障排查指南
1. 别急着敲安装命令先搞懂 Ubuntu 输入法的三层结构在 Ubuntu 上装中文拼音输入法最容易犯的错是上来就sudo apt install一通装完重启然后发现——右下角托盘里那个键盘图标是灰色的或者能打字但没有候选框。这类问题九成不是包没装上而是没搞清楚输入法这三个字在 Linux 上其实是三件不同的事。我先把这件事说透后面所有的操作你都能自己推导出来而不是照着别人博客抄一遍、错一个字母就蒙了。1.1 应用、框架、引擎各管什么Ubuntu 的中文输入是一条三层的链路从上到下依次是应用层、框架层、引擎层。应用层就是你日常用的那些程序——Firefox、Chrome、VS Code、终端、WPS、微信。它们本身不实现拼音它们只负责我有一个输入框谁能给我送字。框架层就是输入法框架常见的是IBus和Fcitx5老一点的是 Fcitx4。框架的作用是常驻后台、监听键盘事件、在光标位置画出候选框、把选中的字塞进应用的输入框里。它约等于 Windows 上的输入法管理器。引擎层才是真正干活的那个拼音、双拼、五笔、仓颉、日语假名都只是挂在框架下面的一个引擎。搜狗输入法 Linux 版比较特殊——它同时打包了引擎和框架适配层所以它对框架版本有强依赖这就是后面很多坑的根源。明白这个分层之后很多现象就能直接解释了。比如英文能打、中文打不出来通常是框架起来了但没启用拼音引擎能打中文但没有候选框一般是框架和应用之间的通信通道IM module没接通重启后失效基本可以锁定环境变量没写对地方。1.2 三套主流方案的横向对比目前 Ubuntu 上跑中文拼音实际可选的路线就三条各自的特点我列成表格你可以直接对号入座。方案组成优点坑点适合谁Fcitx5 内置拼音fcitx5 fcitx5-chinese-addons官方源直接装、Wayland 支持在持续完善、词库可换、无版权顾虑默认词库偏薄需要手动导入候选框样式朴素长期用 Ubuntu 干活、追求稳定的开发者搜狗输入法 Linux 版官方 deb 包 适配层词库和联想强、和 Windows 手感接近依赖特定框架版本新旧框架共存时冲突升级系统后容易崩刚从 Windows 迁移、重度依赖云词库的人IBus 内置智能拼音ibus ibus-libpinyin系统自带、零安装候选框跟手度一般、候选词质量弱、某些应用下会丢焦点只偶尔打几个中文、不想折腾的人这张表里最关键的一行其实是第二行的坑点列。搜狗的问题从来不是装不上而是它会把旧框架作为依赖拽进来然后在某次系统升级后突然失效。我自己在两台机器上踩过完全一样的坑后面第 4 节会详细讲。1.3 我的选型结论如果这台 Ubuntu 是你要长期用来写代码、写文档的主力机我的建议非常明确用 Fcitx5 fcitx5-chinese-addons别装搜狗。理由有三个都很实际。第一是依赖干净。Fcitx5 全系列都在 Ubuntu 官方源里apt一条命令搞定不会引入任何第三方仓库将来升级系统也不会因为某个外部包卡住。第二是不会和系统打架。Ubuntu 默认预装 IBus而 Fcitx5 和 IBus 的关系是二选一只要用im-config明确指定默认框架两者可以干净共存不会互相抢键盘。第三是可折腾空间大。词库可以换、候选数量可以调、模糊音和双拼都能开、用户词库是纯文本文件可以用脚本处理——这些东西对你后期把打字体验调到接近 Windows 手感非常关键而搜狗在 Linux 上留给你的调节余地非常有限。2. 动手前的三步体检能省掉一半返工我见过太多人装完输入法发现不对劲然后反复卸载重装其实问题出在压根没做前置检查。正式安装前先花三分钟把下面三件事确认掉。2.1 先确认你的会话是 X11 还是 Wayland这是最重要的一步因为这两种显示会话下环境变量的写法、候选框的显示方式完全不同。在终端里执行echo $XDG_SESSION_TYPE输出x11说明你跑在 X11 上输出wayland就是 Wayland。Ubuntu 22.04 之后默认给的是 Wayland登录界面右下角那个齿轮里能手动切回 X11。为什么这个区别要命因为在 X11 下输入法框架通过一个叫 XIM 的老协议和应用通信环境变量必须写全而在 Wayland 下GTK 应用走的是text-input协议如果你硬把GTK_IM_MODULE设成fcitxGTK 应用反而会绕开原生协议走回退路径结果就是候选框位置乱飘甚至不显示。我的经验是先按会话类型决定变量怎么写再去装包顺序反了就要多注销好几次。2.2 确认系统版本、架构和现有框架状态顺手把这几条命令跑一遍结果记下来lsb_release -a # 确认是 22.04 还是 24.04 dpkg --print-architecture # 确认 amd64 还是 arm64 dpkg -l | grep -E fcitx|ibus # 看看已经装了什么框架 im-config -l # 列出系统认识的所有输入法框架为什么要看架构因为有些第三方 deb 包只出 amd64如果你在 ARM 的机器上比如某些开发板挂的 Ubuntu下载下来也装不上会直接报package architecture (amd64) does not match system (arm64)。为什么要看现有框架因为 Ubuntu 桌面版默认预装 IBus如果你之前手贱装过 Fcitx4那 Fcitx4 和 Fcitx5 会同时存在很多配置文件会互相覆盖导致你改了 A 文件但生效的是 B。这种问题最难查因为它不报错只是行为不符合预期。2.3 把历史残留清干净如果前面的检查发现已经有 Fcitx4 或者别的旧框架先清掉再装新的sudo apt remove --purge fcitx fcitx-bin fcitx-data fcitx-modules sudo apt autoremove --purge rm -rf ~/.config/fcitx ~/.config/fcitx5这里有个细节很多人忽略配置文件目录要手动删。apt remove --purge只清理系统级的配置家目录下的~/.config/fcitx它会原样留着。而 Fcitx5 在首次启动时如果发现同名配置目录存在会尝试读取里面的旧参数于是你看到的候选词数量、快捷键全是上一个框架的遗留值。注意删~/.config/fcitx5之前先确认里面没有你导入过的自定义词库。词库一般放在~/.local/share/fcitx5/pinyin/和配置目录是分开的删配置不影响词库但删之前顺手ls一下总没错。3. 主推路线Fcitx5 加拼音引擎的完整实操前面铺垫够了现在开始动手。这一节我会把每一步为什么这么做都讲清楚你按顺序执行就行。3.1 一次性把需要的包装齐先更新索引然后把 Fcitx5 全家桶装上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-module-cloudpinyin逐个解释一下这几个包的职责这样将来某个应用打不了字你就知道该去查哪一个。fcitx5是框架本体提供常驻进程和基础能力。fcitx5-chinese-addons是中文附加包里面包含拼音、双拼、五笔、仓颉、注音等引擎拼音就在这个包里这是核心中的核心漏了它你会得到框架在跑但没有任何中文可选的状态。后面四个frontend包是连接器负责让不同类型的应用能连上框架GTK3 对应大部分 GNOME 系应用和老版程序GTK4 对应新一点的 GNOME 应用比如 Ubuntu 24.04 上的一些原生工具Qt5 和 Qt6 对应 KDE 系应用以及大量国产软件。任何一个前端缺了就会出现浏览器能打字但某个软件不行的现象所以建议一口气全装。fcitx5-config-qt是图形配置工具不带 GUI 的话你只能用命令行调参数效率会低很多。fcitx5-module-cloudpinyin提供云拼音联想能力可选装了之后长句的准确率会有明显提升。3.2 环境变量写哪几个、写在哪这是整个流程里最容易出错的环节我拆成两半讲先确定写什么再确定写在哪。需要设置的变量一共三个GTK_IM_MODULEfcitx QT_IM_MODULEfcitx XMODIFIERSimfcitxGTK_IM_MODULE告诉 GTK 系应用去加载 Fcitx 的输入模块QT_IM_MODULE是同样的意思针对 Qt 系应用XMODIFIERS是给老的 XIM 协议用的兜底。三个缺一个对应技术栈的应用就会变成能打英文不能打中文。写在哪取决于你的会话类型场景推荐位置生效范围生效时机X11 会话/etc/environment全系统所有用户重启后X11 会话只要当前用户~/.xprofile当前用户注销重登Wayland 会话~/.config/environment.d/fcitx.conf当前用户的 systemd 会话注销重登只想临时验证终端里直接 export当前终端进程立即~/.config/environment.d/这个目录是 systemd 用户级环境变量的标准位置格式是纯KEYVALUE不要写export不要加引号。文件长这样# ~/.config/environment.d/fcitx.conf GTK_IM_MODULEfcitx QT_IM_MODULEfcitx XMODIFIERSimfcitx提示如果目录不存在mkdir -p ~/.config/environment.d先建出来。文件名必须以.conf结尾否则 systemd 会忽略它。这个坑我踩过排查了二十分钟。如果你的会话是 Wayland我实际测下来的建议是只设QT_IM_MODULE和XMODIFIERS把GTK_IM_MODULE留空。原因是 Wayland 下 GTK4 应用原生支持输入法协议强制设成fcitx会把它推回 XIM 通道候选框就会跟着窗口边缘跑而不是跟着光标跑。这个经验值在不同版本上略有差异你可以先用全量配置测一遍如果不满意再单独去掉GTK_IM_MODULE对比。3.3 用 im-config 指定默认框架环境变量写好了但系统还不知道默认输入法框架是 Fcitx5这一步必须靠im-config来做im-config -n fcitx5执行完它会往~/.xinputrc写一行配置。你可以用cat ~/.xinputrc确认一下正常输出类似run_im fcitx5为什么这一步不能省因为启动输入法进程的其实是显示管理器GDM或桌面会话的启动脚本它会读~/.xinputrc决定拉起哪个框架。环境变量只是告诉应用连哪个框架im-config才决定哪个框架被启动。两者缺一就会出现变量都对但进程没起来的诡异状态。做完这一步注销后重新登录或者干脆重启一次。别偷懒只关终端重开环境变量对已经存在的进程不生效。3.4 首次启动与基础配置重新登录后右上角应该出现一个键盘图标。点它能看到输入法菜单。如果图标没出现在终端里手动拉起看一下报错信息fcitx5 -d --replace-d是放到后台--replace是替换掉已存在的实例。如果这条命令有报错说明包没装全或者有旧框架在占位按提示缺什么补什么。接着打开图形配置界面fcitx5-configtool在输入法标签页里把左边的 Pinyin简体中文拼音添加到右边。注意别选错成 Shuangpin双拼或者 Wubi五笔除非你真的用那个。添加完之后默认的切换快捷键一般是Ctrl 空格。这里有个绕不开的坑GNOME 自己也占用了Ctrl 空格和Super 空格来切换系统输入源。如果你 GNOME 里还留着中文智能拼音这个输入源就会和 Fcitx5 抢同一个快捷键表现为按了没反应或者要按好几次才切过来。解决办法是去设置 → 键盘 → 输入源把除 English (US) 之外的全部删掉只留一个。GNOME 的输入源是给 IBus 用的Fcitx5 有自己的机制不需要在这里注册。3.5 词库、模糊音和双拼按需开装完之后你会发现默认词库偏薄打一些新词、专业术语、人名地名要一个一个字选。这时候两个东西值得配上。第一个是扩展词库。Ubuntu 源里有一个基于百科词条的拼音词库包sudo apt install fcitx5-pinyin-zhwiki装完重启框架就能用。如果源里没有这个包也可以手动下载词库文件格式是.dict丢到~/.local/share/fcitx5/pinyin/dictionaries/目录下重启生效。第二个是模糊音。南方口音的朋友对这个需求很强烈zh/z、ch/c、sh/s、n/l、前后鼻音这些都是常开的。在fcitx5-configtool的拼音设置里能找到模糊拼音开关勾选即可不需要改配置文件。至于双拼它的收益取决于你愿不愿意重新练一遍键位。我的看法是如果你每天打字量在五千字以上双拼值得投入两周适应期长期收益很明显如果只是偶尔写点东西用全拼就够了别折腾。4. 备选路线搜狗输入法的安装与共存风险前面说过我推荐 Fcitx5但确实有很多人就是习惯搜狗的联想和词库。那这一节我把搜狗这条路讲清楚包括它到底会在哪里出问题。4.1 安装步骤从官方渠道下载 Linux 版 deb 包然后sudo dpkg -i sogoupinyin_*.deb sudo apt -f install第二行是必须的因为dpkg不会自动解决依赖直接把包扔进去很可能因为缺库而处于未配置状态。apt -f install会尝试自动补上缺失的依赖。如果下载的是较新的版本它一般会自带框架适配层如果是老版本这一步可能会把 Fcitx4 作为依赖一起装进来。装完先别急着注销用下面这条命令看看拉进来了什么apt-cache rdepends fcitx 2/dev/null dpkg -l | grep -i sogou如果有 Fcitx4 相关的包被拉进来你就得做一个决定要么放弃 Fcitx5 全面转向搜狗那套要么放弃搜狗。两者共存是行不通的因为 Fcitx4 和 Fcitx5 会争抢同一个环境变量和同一个会话启动入口表现就是有时候能打有时候不能打非常难受。4.2 装完必须做的三项验收搜狗在 Ubuntu 上的验收不能只看能不能打字因为它的失效往往是渐进式的。装完重启后按这三项挨个测第一项打开 Firefox 或者 Chrome随便找个搜索框输入一段拼音。要看的不是能不能出字而是候选框是不是紧贴光标。如果候选框出现在窗口左上角或者屏幕中间说明 GTK_IM_MODULE 那条链路有问题。第二项打开 VS Code 或者终端再测一遍。这一类是 Electron 或 Qt 应用走的是另一条通道能验证 QT_IM_MODULE 是否正常。第三项重启系统再打开同样的应用测一遍。这一步专门用来验证环境变量是不是写到了能持久生效的位置。前面说过只在终端里export的话重启就没了。三项都过说明装得干净。有一项不过就按第 5 节的方法去查环境变量。5. 让配置重启不失效环境变量与自启的正确姿势这一节是所有问题的公共根因值得单独拎出来讲透。因为输入法重启后失效这个现象我在论坛上见过不下几十次答案基本都在这里。5.1 三个配置文件的生效顺序Linux 会话启动时环境变量的加载是有先后顺序的后面的会覆盖前面的/etc/environment系统级最早加载对所有用户生效。格式是纯KEYVALUE不能写export不能用$HOME这类变量展开。~/.config/environment.d/*.conf用户级由 systemd 用户管理器读取只对 systemd 管理的会话生效。~/.xprofile由显示管理器在 X11 会话启动时执行本质是个 shell 脚本可以写export也可以用变量展开。注意~/.xprofile只在 X11 会话下被读取Wayland 下这个文件根本不执行。这就是为什么有人在 X11 上配得好好的切到 Wayland 就全废了。还有一个常见的误解是~/.bashrc。很多人图省事把输入法变量写进~/.bashrc结果发现只有终端里能用图形界面的应用完全不受影响。原因很简单~/.bashrc只在交互式 shell 启动时执行GUI 应用压根不经过 shell。5.2 Wayland 下的取舍策略Wayland 这几年变化很快不同 Ubuntu 版本的行为不完全一致。我给一个实测下来比较稳的策略先按完整版配三个变量都设重启后测试。如果候选框位置正常就保持如果出现候选框乱飘、输入延迟、或者某些 GTK4 应用完全打不了字就去掉GTK_IM_MODULE只留另外两个再测。这个试两次的做法听起来不优雅但比查文档快得多因为不同发行版、不同桌面环境、不同框架版本的组合太多了没有一份文档能覆盖全部。注意改完~/.config/environment.d/下的文件后如果想不重启就验证可以执行systemctl --user daemon-reload然后注销重登。直接重启当然更保险。5.3 自启与托盘别指望它自己起来正常情况下im-config配好之后Fcitx5 会随会话自动启动。但如果发现每次登录都要手动敲fcitx5 -d说明自启链路断了。这时有两个补救办法。一是检查~/.xinputrc内容对不对必要时重新执行im-config -n fcitx5。二是直接用桌面环境的自启功能兜底在启动应用程序里新增一项命令填fcitx5 -d。这个办法简单粗暴但极其有效代价是启动会比原生方式晚一两秒刚开始那几秒打字可能还是英文。至于托盘图标如果菜单里显示成了灰色的禁用状态点一下启用就行。有时候升级后图标会变成问号或者干脆消失一般是图标主题缺了对应资源装个fcitx5-material-color之类的主题包就能恢复。6. 故障排查实录那些让我查了半天的坑前面是怎么装这一节是装完不对怎么查。我把这几年遇到过的典型案例整理出来每个都附上排查路径。6.1 能打英文中文候选框不出现这是最高频的问题。排查顺序应该是这样的先确认拼音引擎加了没有fcitx5-configtool里看输入法列表再确认框架进程在不在ps aux | grep fcitx5最后才是环境变量。如果引擎在、进程在那就是应用侧连不上。此时最有效的工具是fcitx5-diagnose这条命令会输出一大段信息包括当前会话类型、各个环境变量的实际值、各个前端模块的安装状态、甚至能检测出常见的配置错误。它会直接把可疑项标出来比如GTK_IM_MODULE 设置为 xim建议修改为 fcitx这种照着改就行。老实说学会用这个命令之后我排查输入法问题的时间至少缩短了一半。6.2 特定应用打不了字不同的应用走不同的输入通道所以只有某个软件不行这个现象指向性非常明确现象大概率原因处理方式只有 Chromium 系浏览器不行启动时未加载 GTK 输入模块确认GTK_IM_MODULE已设置并从桌面图标启动而非命令行只有 VS Code 等 Electron 应用不行走了 XWayland 且 XIM 配置缺失确认XMODIFIERSimfcitx或把 VS Code 切到 Wayland 原生模式只有 Qt 程序如 WPS不行fcitx5-frontend-qt5未安装补装对应前端包并注销重登输入时延极高、偶尔丢字云拼音网络请求超时在拼音设置里关掉云拼音试试候选框出现在屏幕角落Wayland 下强制走了 XIM去掉GTK_IM_MODULE让应用走原生协议这张表我建议存下来因为 Ubuntu 换版本的时候这些问题会以新的形式重现但排查逻辑是不变的先定位是哪个通道断了再补对应的包或变量。6.3 虚拟机和 WSL 里的额外坑如果你是在 VMware 或 VirtualBox 里跑 Ubuntu有一个宿主和客户机抢快捷键的问题。你在虚拟机里按Ctrl 空格结果宿主机先响应了或者虚拟机软件把组合键当成了自己的功能键。解决办法是在虚拟机软件的快捷键设置里把相关的组合键改成发送到客户机或者简单点——退出虚拟机的鼠标键盘独占模式让按键直接穿透进去。至于 WSL 场景我的建议是别在 WSL 里折腾输入法。WSLg 的图形层要经过一层协议转换输入法框架在里面跑起来本身就别扭字体渲染和候选框位置也都是额外变量。更实用的做法是把界面留在 Windows 侧——用 VS Code 的远程连接功能连到 WSL 里写代码输入法用 Windows 自带的零配置零风险。这个组合我用了一年多稳定性比在 WSL 里硬装输入法高出一个量级。6.4 常见问题速查表把上面的内容压缩成一张可以直接贴在手边的表症状第一条命令重点关注完全没反应ps aux | grep fcitx5进程是否存在有进程无候选fcitx5-diagnose环境变量与前端包重启后失效cat ~/.xinputrc默认框架是否正确快捷键冲突检查 GNOME 输入源设置是否残留 IBus 输入源某应用单独失效dpkg -l | grep frontend对应前端包是否安装候选词太少看词库目录是否装了扩展词库7. 把打字体验调到接近 Windows 的手感装好能用只是及格线真正舒服还需要一点调优。这一节讲几个投入产出比很高的调整。7.1 词频学习和用户词库Fcitx5 的拼音引擎会记录你的选词习惯存在~/.local/share/fcitx5/pinyin/user.dict。这个文件是二进制的不要用文本编辑器打开但可以直接复制备份。换机器的时候把它拷过去新机器第一天就有你的用词习惯这个体验提升非常明显。有个小技巧值得试如果你经常输入固定的专业术语或者公司内部名词可以在配置里把用户词频优先打开然后连续选几次正确的词一般三五次之后它会把这个词排到候选第一位。比手动造词省事得多。7.2 候选数量、字体和渲染默认候选数量是 5 个我一般调到 7。为什么不是越多越好因为候选框太宽会遮挡输入框上方的界面内容尤其是在小屏幕笔记本上。7 个是我用 14 寸屏幕试出来的平衡点超过这个数就开始影响阅读了。字体方面如果你觉得候选框里的字发虚八成是字体渲染的问题而不是输入法的问题。可以在主题设置里换成系统里已经调好渲染的中文字体会比默认字体清晰不少。7.3 配置目录的备份与迁移整个输入法的个性化配置集中在两个目录~/.config/fcitx5/配置文件包括快捷键、主题、引擎开关~/.local/share/fcitx5/词库、用户数据换电脑或者重装系统之前把这两个目录打包存一份新机器上装完框架之后直接覆盖回去重启就是原来的手感。这个操作我在做系统重装的时候基本是标配五分钟能省掉大半小时的重新配置。最后分享一个小细节。我习惯在装修完之后跑一遍fcitx5-diagnose ~/input-method-report.txt把当时的完整状态存一份。等哪天出问题了拿现在的结果和当时那份对比差异项基本就是问题所在。这个习惯是从排查网络问题时学来的用在输入法上一样好使——毕竟很多时候以前好好的现在不行了答案就藏在变化里。
