診斷與日誌
出字異常時先看這一頁,再去常見問題對號入座。快速開始裡只留了最常說的三條,完整口徑在這裡。
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 會丟,終端接著持續自動送出 Enter。
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