诊断与日志
出字异常时先看这一页,再去常见问题对号入座。快速开始里只留了最常说的三条,完整口径在这里。
1. 先跑 auri-doctor
Section titled “1. 先跑 auri-doctor”装完合包就有这个命令。不带参数是只读的,什么都不改:
auri-doctor四个开关:
| 命令 | 做什么 |
|---|---|
auri-doctor | 打印一份链路报告,末尾给出可直接执行的建议 |
auri-doctor --runtime | 把 Runtime 那行展开成完整快照:libauri、面板、词库、配置路径,以及被忽略的变量和异常 |
auri-doctor --repair-xim | 启用用户级 systemd 单元 auritype-xim.service,把 ibus-x11 桥接拉起来。给 Java / IntelliJ 这类走 XIM 的应用用 |
auri-doctor --repair-gnome-caret | 安装并启用 GNOME Shell 光标跟随扩展。执行完必须注销并重新登录一次 |
auri-doctor --enable-jbr-wayland | 可选:往 JetBrains 的 vmoptions 里加一行 -Dawt.toolkit.name=WLToolkit,让 JetBrains 直接走 Wayland 而不是 XWayland |
报告里的 JetBrains 一节只读不改:它列出你的 vmoptions 文件和当前状态(already set 或 XWayland),加不加由你决定。
2. 报告怎么看
Section titled “2. 报告怎么看”auri-doctor 的输出是逐行的 [✓] / [!] / [✗],顺序固定:
Session Type — 当前是 wayland 还是 x11,后面括号里是桌面名。Wayland 下才需要关心光标扩展。
Core Engine — 当前 IBus 引擎。应该是 auritype-pinyin;显示别的说明你还没在系统输入源里切过来。
Runtime — 默认只有一行:模式、实际加载的 libauri 路径、异常列表。mode=installed 表示走的是 /usr/share/auritype 下的安装产物;installed 模式会忽略 CARGO_TARGET_DIR 这类开发工具链变量。看到 anomalies 非空,再跑 --runtime 展开。
GNOME Caret Extension(仅 GNOME)— 扩展 ID 是 auritype-window-origin@auritype。三件事依次检查:扩展目录在不在(/usr/share/gnome-shell/extensions/auritype-window-origin@auritype)、总线名 com.auritype.CaretRoot 有没有被持有、Shell 侧的 IBus 连接是否健康(manager、panel 是否 attached、候选弹窗是否已接管、当前引擎)。
扩展文件装了但总线没被持有,是典型的「刚装完还没重登」——Shell 只在登录时扫描扩展目录,所以报告直接让你执行 --repair-gnome-caret 并注销重登。
XWayland Subsystem — 这一段管的是 Java、Electron 老版本和其它走 XIM 的程序:
| 字段 | 期望值 |
|---|---|
DISPLAY | 已设置;Wayland 会话下通常是 :1 之类的 XWayland 显示 |
XMODIFIERS | @im=ibus |
IBUS_ENABLE_SYNC_MODE | 在 ibus-x11 进程的环境里为 1 |
| XIM selection | @server=ibus 有 owner |
ibus-x11 进程 | 正在运行(/usr/libexec/ibus-x11) |
任意一项不满足,报告会写明「Java/AWT 应用将无法输入中文」,并给出 auri-doctor --repair-xim。
ibus-daemon — 没运行就单独报一行。
3. 日志在哪里
Section titled “3. 日志在哪里”~/.local/state/auritype/auritype.log目录取自 $XDG_STATE_HOME,没设置时默认 ~/.local/state。
| 项 | 值 |
|---|---|
| 目录权限 | 0700(只有你自己能进) |
| 文件权限 | 0600 |
| 轮转 | 单个 5 MiB,保留 3 份备份 |
| 启动清理 | 最多留 20 个日志文件,超过 30 天的删掉 |
| 主日志级别 | 由 IBus 拉起(带 --ibus)时是 INFO 且不写控制台;从终端手动启动时是 DEBUG 并输出到控制台 |
日志不记录组合串、候选与上屏文本,记的是引擎状态、链路和异常。要更全的启动快照,用 AURI_DEBUG=1 启动,或者跑 auri-doctor --runtime——完整 dump 只出现在这两处,不会落盘到 ~/.config/auritype 等用户目录。
4. 环境变量
Section titled “4. 环境变量”下面这些会改变输入法加载什么、往哪写。正常安装一个都不需要设置;列出来是因为排查「装了新包却像旧行为」时,往往是终端里继承了某个变量。
| 变量 | 作用 |
|---|---|
AURI_CABI_LIB | 指定 libauri 动态库路径 |
AURITYPE_PANEL | 指定候选面板可执行文件 |
AURI_LEXICON_ROOT | 指定词库根目录 |
AURI_CONFIG_PATH | 指定用户配置文件,覆盖默认的 ~/.config/auritype/config.toml |
AURI_SYSTEM_CONFIG_PATH | 指定系统模板配置 |
AURI_DEBUG | 置真则日志转 DEBUG,并打印完整 Runtime 快照 |
AURI_ATSPI | 辅助功能(无障碍)相关开关 |
AURI_W0_WAIT_MS | 首次渲染的等待毫秒数 |
AURI_PANEL_LOG | 面板自己的日志位置 |
显式设置的这九个永远优先。除此之外,源码树里跑(dev 模式)时 CARGO_TARGET_DIR 可以参与候选库查找;已安装模式下它被忽略,并且会在日志里留一条异常。
5. 重载、污染与回退
Section titled “5. 重载、污染与回退”装完包或更新后重载引擎:
ibus restart在普通终端里执行。从 IDE 或 agent 的内置终端执行会带进 CARGO_TARGET_DIR、CURSOR_*、VSCODE_*,污染环境经 daemon 传给整棵子树,引擎可能加载到沙箱里的旧库。生产启动器会 unset 这些变量,但挡不住已经被污染的 daemon 父进程。
daemon 已经被污染时,退出后用干净的 systemd 用户会话环境重新拉起:
ibus exitibus-daemon -drx别在按键中间重启。重启正好落在 Enter 按下与抬起之间,key-up 会丢,终端接着持续自动回车。
XIM 桥接由 systemd 用户单元监督。auritype-xim.service 装在 /usr/lib/systemd/user/,ibus restart 后它的监督循环会在 30 秒内补起 ibus-x11。
扩展相关的改动要注销重登。光标跟随扩展的脚本、启用状态变了,Shell 只在登录时扫描,ibus restart 解决不了。
卸载会把你切回英文。ibus-auritype 的 prerm 脚本遍历当前活跃的图形会话,凡是引擎正处于 auritype-pinyin 的普通用户(UID ≥ 1000),会被切到 xkb:us::eng,同时全局禁用 auritype-xim.service——免得卸载后引擎消失、登录时 IBus 找不到它。
sudo apt remove --purge auritype