4-6 安装中文输入法 · 波仔的树莓派课

📄 一句话概括

系统默认只会打英文——这一节把中文输入装上去：弄清「框架 / 引擎 / 前端」三层关系，按顺序装包、用 im-config 把系统指到新框架、重启、添加拼音引擎，并配一张「打不出中文」的排查表。

📝 本节和前面几节的关系

4-5 讲了「怎么装包」——本节就是把它用在唯一一个「装完还要配置」的软件上。 4-3 讲了权限与 sudo、4-4 讲了 /etc 与 ~ 各放什么——本节涉及的配置文件正好落在两处：系统级的在 /etc，你个人的在 ~。 这是本课第一节「纯桌面操作」的课：装包能 SSH 做，但最后的启用必须在桌面里完成（原因见第六节）。

一、为什么系统装好了却打不出中文

因为「能显示中文」和「能输入中文」是两件完全不同的事：

能力	靠什么	系统默认有没有
显示中文	中文字体文件	多半有（没有就是方块字）
输入中文	输入法框架＋中文引擎	默认没有

道理很简单：键盘上只有 26 个字母键。你敲 nihao 要变成「你好」，中间必须有个程序在监听按键 → 拼出候选 → 送进应用。这套东西默认不装。

先分清三层（这是本节最该搞懂的结构，后面一切命令都围绕它）：

层	干什么	例子
输入法框架（IM framework）	「总管家」：接住按键、管切换、把结果送给程序	fcitx5、ibus
输入法引擎（engine）	「干活的」：具体的一种打字方式	拼音、双拼、五笔、注音
前端模块（frontend）	「接头」：让不同类型的程序都能用上框架	gtk3／gtk4／qt5 各一个

💡 用一句比喻记住

框架是插座，引擎是插在上面的电器，前端是各种转接头。 所以「装了个框架却打不出字」通常不是框架的问题——是忘了插引擎，或者缺了某个转接头。

二、两条路线，选一条：`fcitx5` 还是 `ibus`

Linux 上这两套并存，选一个就行：

	fcitx5（推荐）	ibus
定位	轻量、对 Wayland 支持好	老牌、GNOME 系原生
中文引擎	`fcitx5-chinese-addons`：拼音／双拼／五笔／仓颉等一包全给	`ibus-pinyin`／`ibus-libpinyin` 等分开装
配置工具	`fcitx5-config-qt`（图形界面）	`ibus-setup`
在树莓派上的现状	社区主流选择	也能用，但近年更新慢

本课按 fcitx5 走（3-1 已经讲过本代桌面默认 Wayland ＋ labwc，而 fcitx5 对 Wayland 支持更完整，这一点直接决定选择）。

⚠️ 老教程失效清单（本节的坑全在这）

① scim：早死多年，别碰。 ② fcitx（4 代）：已被 fcitx5 取代，在 Wayland 下问题多，新系统上不要再用 4 代。 ③ 手改 /etc/environment 塞环境变量：老做法、全局生效、容易写错。现在交给 im-config 更稳（第六节）。 ④ 教材若是台湾译本，讲的可能是注音／仓颉——本课全简体，用拼音；如果你确实需要注音，fcitx5-chinese-addons 里也带。

三、先装字体（顺序真的有讲究）

字体要放在输入法之前装——否则你打完拼音，候选框里可能是一串方块，你还以为是输入法没装上，白折腾半天。

包	是什么	建议
`fonts-noto-cjk`	Google 的 Noto 中日韩字体	首选：覆盖全、字形好看
`fonts-wqy-zenhei`	文泉驿正黑	体积小，老教程常提
`fonts-wqy-microhei`	文泉驿微米黑	同上

装一套就够了，别全装（树莓派的 SD 卡不大，CJK 字体动辄几百 MB）：

sudo apt update
sudo apt install -y fonts-noto-cjk

四、正式安装：四条命令

# 1. 刷新清单（4-5 讲的，永远第一步）
sudo apt update

# 2. 装框架 + 中文引擎 + 三个前端 + 图形配置工具
sudo apt install -y fcitx5 fcitx5-chinese-addons \
    fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5 \
    fcitx5-config-qt

# 3. 装中文字体（如果第三节还没装）
sudo apt install -y fonts-noto-cjk

每个包的作用（对照第一节那三层看）：

包	属于哪一层	作用
`fcitx5`	框架	总管家本体
`fcitx5-chinese-addons`	引擎	中文引擎集合（拼音、双拼、五笔…）——打不出中文常常就是漏了它
`fcitx5-frontend-gtk3`	前端	让 GTK3 程序能用（文件管理器、终端）
`fcitx5-frontend-gtk4`	前端	让 GTK4 程序能用（新版应用）
`fcitx5-frontend-qt5`	前端	让 Qt 程序能用（部分第三方应用）
`fcitx5-config-qt`	工具	图形配置界面——用来添加拼音引擎

💡 为什么不一次只装框架

如果只装 fcitx5 而不装 fcitx5-chinese-addons，你会发现：框架在跑、图标也在，但配置里加不上拼音——因为拼音是引擎提供的，不是框架自带的。 一条最实用的记法：框架＋中文引擎＋三前端，四类一起装，缺一不可。

五、告诉系统「用这个框架」：`im-config`

装好包只完成一半。系统还不知道该用哪个输入法框架——这就要 im-config 出场。

im-config -n fcitx5

参数	含义
`-n fcitx5`	把默认输入法框架设为 fcitx5（`-n` ＝非交互式，直接指定）

⚠️ 这一步必须在「图形桌面」里做，别在 SSH 里做

im-config 管的是你的桌面会话该用哪个输入法——它写的是你自己家目录里的配置（~/.xinputrc），并且要在有新桌面会话时生效。在 SSH 无头连接里跑它，虽然命令不报错，但真正起作用的是你在桌面上登录的那一次会话——所以本节的活儿请开桌面终端做。（sudo apt install 那几步在 SSH 里做没问题，只有这一步和后面「添加拼音引擎」必须回桌面。这是本课环境约定里唯一一处「命令行搞不定」的地方。）

顺手确认它写进去了：

cat ~/.xinputrc 2>/dev/null
# 应该能看到指向 fcitx5 的内容

关于环境变量（知道即可，不必手动改）：

老教程会让你往 ~/.profile 或 /etc/environment 里加这么几行：

GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitx

现在不需要手动加了——im-config 会替你把该设的设好。手改反而容易出两个问题：① 值写错（写成 fcitx5 等）导致不生效；② 写在全局文件里影响所有用户。让工具做，比抄教程稳。

六、重启，然后添加拼音引擎

为什么必须重启：输入法框架要在新的桌面会话开始时才被拉起来。

sudo reboot

重启回来后，按这个顺序操作（纯鼠标，全在桌面）：

#	动作	在哪
1	看顶部状态栏右侧有没有多出一个输入法图标（键盘／`A`／`拼` 之类）	顶栏
2	点它 → 选 Configure（配置）	弹出菜单
3	切到 Input Method（输入法）标签页	配置窗口
4	点 Add（添加）→ 取消勾选「Only Show Current Language」	关键一步
5	搜索 Pinyin → 选中 → 确定	列表里出现「拼音」
6	把「拼音」拖到列表最上面	让它成为默认
7	关闭窗口（设置会自动保存）	—

⚠️ 第 4 步是「找不到拼音」的唯一原因

配置窗口默认勾着「只显示当前语言」——而你的系统界面语言是英文，所以拼音被过滤掉了，列表里空空如也。 去掉那个勾，Pinyin 立刻就出现了。 这一条几乎每个新手都会卡一次，中文论坛上的「fcitx5 装完找不到拼音」九成是它。

七、测试与切换

切换键（默认）：

快捷键	作用
`Ctrl` + `空格`	切换中／英（最常用）
`Shift`（或 `Ctrl` + `Shift`）	中英之间临时切换（视配置而定）
图标颜色变化	英文状态图标偏灰，中文状态会变亮／变色

在三个地方各试一次（这一步才算真验收）：

测试场地	怎么试	为什么测它
终端	`Ctrl` + `Alt` + `T` 开终端，切中文打几个字	测 gtk3 前端
浏览器	开 Chromium，在地址栏／搜索框打字	测另一条前端链路
文本编辑器	打开文本编辑器（如 `nano` 或图形编辑器）	测普通应用

能打出中文＝成功。 只要有一处打不出，看下一节的表。

八、「打不出中文」排查表

现象	最可能的原因	怎么办
配置里找不到 Pinyin	配置窗口勾了「只显示当前语言」	取消那个勾（第六节第 4 步）
顶栏根本没有输入法图标	框架没起来／`im-config` 没设	检查 `~/.xinputrc`；在桌面里重新跑一次 `im-config -n fcitx5`；然后重启（不是注销）
图标在，但某些程序里打不出	缺对应的前端模块	看你缺哪个：装 `fcitx5-frontend-gtk4`（新版 GTK 应用）或 `-qt5`（Qt 应用），装完重启
候选框里是方块字	中文字体没装	`sudo apt install fonts-noto-cjk`（第三节）
框架似乎没在跑	自启动没生效	先手动拉起来看是否有反应：`fcitx5 -d`；如果手动能起来，就是自启动的问题（可做一个 autostart 项）
手动启动报 DBus 相关的错	在 SSH 里跑的	回桌面做（第五节那个警告）
重启后又变回英文输入	拼音没排在列表最前	打开配置，把 Pinyin 拖到第一位
按 `Ctrl` + `空格` 没反应	快捷键被别的程序占了	在配置里改一个切换键
装的时候提示空间不足	SD 卡满了	`df -h` → `sudo apt clean && sudo apt autoremove`（4-5）

一条通吃的排序：先查「配置里有没有拼音」→ 再查「字体」→ 再查「前端」→ 最后查「自启动」。 按这个顺序找，基本两分钟定位。

九、动手 Demo：装好、验收、并且会救

第一步：装（可以在 SSH 或桌面终端做）

sudo apt update
sudo apt install -y fcitx5 fcitx5-chinese-addons \
    fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5 \
    fcitx5-config-qt fonts-noto-cjk

第二步：确认包装齐了（一条命令对账）

for p in fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3 \
         fcitx5-frontend-gtk4 fcitx5-frontend-qt5 \
         fcitx5-config-qt fonts-noto-cjk; do
  if dpkg -l "$p" 2>/dev/null | grep -q "^ii"; then
    echo "✅ $p"
  else
    echo "❌ 缺 $p"
  fi
done

第三步：设为默认框架（必须在桌面终端做）

im-config -n fcitx5
cat ~/.xinputrc

第四步：重启并添加拼音

sudo reboot

重启回来后按第六节那张表点完七步。

第五步：验收（打这几个字试试）

树莓派    →  shumeipai
权限      →  quanxian
命令行    →  minglinghang

看到什么算成功：

检查点	预期
第二步	八行全是 ✅（缺哪个就补装哪个）
`cat ~/.xinputrc`	内容指向 fcitx5
第四步之后	顶栏右侧出现输入法图标
配置窗口	去掉那个勾后，能搜到 Pinyin 并添加成功
打字	切中文后打 `shumeipai`，候选框里出现「树莓派」

万一还是不行——手动拉起框架看报错（在桌面终端里跑）：

fcitx5 -d            # -d 表示在后台跑
# 然后再打开配置窗口试一次

「读结果」提示：第二步那条循环是本节的验收集——它把「装没装全」变成了一眼可见的清单。以后遇到任何「装完不生效」的问题，都可以照这个思路：先对账，再配置，最后才怀疑玄学。

十、30 秒实验

验证「前端模块决定哪个程序能用输入法」。

# 1. 先看看你装了哪些前端
dpkg -l | grep fcitx5-frontend

# 2. 假装「缺一个前端」——记录一下当前状态，然后把 qt5 前端卸掉
sudo apt remove -y fcitx5-frontend-qt5

# 3. 重启（或注销重登）后，去找一个 Qt 写的程序打字试试
#    再回到终端／浏览器这些 GTK 程序打字
#    → 你会发现：有的地方能打，有的地方打不出

# 4. 装回来（这才是本节的正解）
sudo apt install -y fcitx5-frontend-qt5

你会看到：删掉某个前端后，受影响的是「那一类程序」，而不是「全部」。

这 30 秒你收获的是：「输入法装好了，但某个程序打不出字」这类怪现象，根子在「前端」，不在「框架」。 以后不用重装整个输入法，只要补那一个前端包——这是效率上的巨大差别。

（不想动系统的同学，跑第 1 步就够了：先看清自己有哪些前端，遇到问题就知道该补哪一个。）

十一、常见误区

「装了框架就能打中文」：不行。框架只是管家，中文能力来自引擎（fcitx5-chinese-addons）。
「字体和输入法没关系」：有关。没中文字体，候选框显示成方块，你会误判成「输入法没装上」。
「配置里搜不到拼音，是包没装」：先去掉「只显示当前语言」那个勾——这是绝大多数人的真实原因。
「im-config 可以在 SSH 里跑」：命令不报错，但真正生效的是桌面会话。这一步请在桌面终端做，然后重启。
「继续用 fcitx 4 代也没差别」：在新系统差别很大——本代桌面是 Wayland，fcitx5 才支持好。
「手改 /etc/environment 更彻底」：更容易出错，而且全局生效影响所有用户。让 im-config 处理。
「中英切换不了，只能重装」：先查快捷键是否被占用，再查拼音有没有排在最前——重装是最后一步。
「一定要重启吗，注销不行？」：重启最稳。输入法框架要在新的桌面会话里被拉起，注销有时不彻底——这一个地方值得多花 30 秒。

自测三问

1. 输入法的三层是什么？哪一层缺了会「配置里加不上拼音」？（**框架（fcitx5）／引擎（fcitx5-chinese-addons）／前端（gtk3·gtk4·qt5）**；**缺引擎**——拼音是引擎提供的） 2. 装完 fcitx5、重启后，配置窗口里搜不到 Pinyin，第一步该做什么？（**取消勾选「只显示当前语言（Only Show Current Language）」**，然后搜 Pinyin 并拖到列表最前） 3. 为什么「字体」要放在「输入法」之前装？（**否则候选框里显示成方块字**，你会误以为输入法没装成功，白折腾）

☑ 第四章完结 —— 教材这一章已读完全部六节：搞清命令行背后的机制、把常用指令按九组过了一遍、学会用户与文件权限、摸清整棵目录树、掌握 apt 装卸载，最后把中文输入法装上
☑ 第五章使用树莓派架设服务器 —— 已完结：架设 FTP 服务器（让这块板子开始给别人干活：架起 Web 服务器、接上 PHP 让它会现算、装上数据库让它能记东西、架起 FTP 服务——LAMP 这套后台已经在你自己的板子上跑通）