macOS 鼠须管配置：雾凇拼音安装、Git 词库管理与 WezTerm 兼容

2025年11月17日 | Ruichen Zhou | 约 17 分钟阅读

系列文章：本文是「Rime 输入法」系列的第 1 篇。

macOS 鼠须管配置：雾凇拼音安装、Git 词库管理与 WezTerm 兼容（本文）

Rime 跨平台迁移：macOS 鼠须管到 Windows 小狼毫 + OneDrive 词库同步

macOS 鼠须管配置：雾凇拼音安装、Git 词库管理与 WezTerm 兼容

这篇记录在 macOS 上配置鼠须管（Rime 的 macOS 前端）的完整过程：安装鼠须管、引入雾凇拼音方案、用 Git 管理词库更新，以及解决在 WezTerm 终端中遇到的三个具体兼容问题（Shift 切换残留字符、终端默认英文、小键盘回车行为不一致）。

Rime 和各平台前端

Rime 是一个输入法“引擎”，不同系统上用不同的“前端”把它挂到桌面环境里：

Linux
- 通过框架集成：
  - IBus-Rime
  - Fcitx / Fcitx5-Rime
Windows
- 前端叫 小狼毫 (Weasel)
- 安装后在系统输入法列表里选择小狼毫
macOS
- 前端叫 鼠须管 (Squirrel)
- 本文主要讨论这一部分
Android
- 比较常见的是“同文输入法 (Trime)”等

这几个前端的界面和集成方式不同，但底层的词库、方案、YAML 配置基本是一套逻辑。这也是 Rime 的一个实际优点：配置可以在多平台之间复用（通过 Git 同步 Rime 配置目录即可）。

安装鼠须管

3.1 使用 Homebrew 安装（推荐）

如果已经在用 Homebrew，安装鼠须管的命令很简单：

brew install --cask squirrel

安装完成后：

退出当前登录用户或重启一次（让输入法进程正常加载）；
打开 系统设置 → 键盘 → 文本输入 → 输入源；
点击“添加”，搜索“鼠须管”，添加为输入法。

3.2 输入法配置目录

鼠须管的用户配置目录在：

~/Library/Rime

后面所有自定义配置、方案、用户词库，都会放在这个目录里。 建议尽量只改这里，不要碰系统目录下的默认配置。

引入雾凇拼音

Rime 默认附带的拼音方案比较基础。为了有更好的词库和默认配置，我使用社区维护的 雾凇拼音 (Rime Ice)：

项目地址（可自行搜索）：iDvel/rime-ice

4.1 手动方式（概念说明）

最朴素的用法是：

从仓库下载项目中的方案文件（若干 .yaml 和词库文件）；
把这些文件放入：
```
~/Library/Rime
```
如果项目里有示例的 default.custom.yaml / squirrel.custom.yaml，可以对比自己的配置，选择性合并（不要直接覆盖自己的改动）；
在菜单栏点击鼠须管图标，选择“重新部署”。

这已经能正常使用了，但后续更新词库会比较麻烦，需要你反复下载、覆盖。

4.2 推荐方式：直接把 `~/Library/Rime` 变成一个 Git 仓库

更优雅的方式是直接把雾凇拼音仓库克隆到 ~/Library/Rime：

# 如果你之前已经有 Rime 配置，建议先备份
mv ~/Library/Rime ~/Library/Rime.bak

# 将雾凇拼音的仓库克隆到 Rime 配置目录
git clone https://github.com/iDvel/rime-ice ~/Library/Rime

这样做有几个好处：

~/Library/Rime 变成了雾凇拼音的一个 完整 Git 仓库；
以后更新只需要 git pull；
仓库内自带的 .gitignore 会忽略 *.custom.yaml，你的个人配置不会被上游影响。

克隆完成后，记得重新部署一次鼠须管，让新方案生效：

切换到鼠须管输入法；
菜单栏图标 → “重新部署”（或 Ctrl + Option + ~ 快捷键）；
等到系统提示部署完成。

到这里，你已经有了：

Rime 引擎；
鼠须管前端；
雾凇拼音方案与词库；
并且整个配置目录在 Git 管理之下，后续可以无痛更新。

用 Git 管理词库

有了 Git 之后，雾凇拼音的维护会变得简单、可预期。

5.1 `git status`：个人配置为什么“看不见”？

在 ~/Library/Rime 下执行：

cd ~/Library/Rime
git status

常见输出类似：

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

而我们明明已经创建或修改了 default.custom.yaml、squirrel.custom.yaml，为什么 Git 说“工作区是干净的”呢？

原因是：雾凇拼音仓库中通常有类似配置：

*.custom.yaml

也就是说：

*.custom.yaml 被有意 排除在 Git 管理之外；
你的个人配置完全属于“本地私有”，不会出现在 Git 提交里；
上游更新词库、Lua、schema 时也不会覆盖你的改动。

这个状态对我们来说非常理想，可以理解为：

上游管词库和默认方案，我只用 patch 文件管自己的习惯；两者互不打扰。

5.2 更新词库的标准姿势

以后每隔一段时间，你只需要在终端运行这一行命令：

cd ~/Library/Rime && git pull && /Library/Input\ Methods/Squirrel.app/Contents/MacOS/Squirrel --reload

这条命令做了三件事：

进入配置目录
```
cd ~/Library/Rime
```
从 GitHub 拉取最新雾凇更新
```
git pull
```

让鼠须管重新部署配置

/Library/Input\ Methods/Squirrel.app/Contents/MacOS/Squirrel --reload

一次真实的 git pull 输出大概是这样（节选）：

remote: Enumerating objects: 267, done.
remote: Counting objects: 100% (267/267), done.
remote: Compressing objects: 100% (148/148), done.
remote: Total 222 (delta 187), reused 102 (delta 74), pack-reused 0
Receiving objects: 100% (222/222), 202.39 KiB | 1.84 MiB/s, done.
Resolving deltas: 100% (187/187), completed with 34 local objects.
From https://github.com/iDvel/rime-ice
   2a25d90..0802d2a  main       -> origin/main
Updating 2a25d90..0802d2a
Fast-forward
 README.md                        |    9 +-
 cn_dicts/base.dict.yaml          | 3714 +++++++++------
 cn_dicts/ext.dict.yaml           | 1175 +++--
 cn_dicts/tencent.dict.yaml       | 5020 ++++++++++----------
 ...
 rime_ice.schema.yaml             |  148 +-
 40 files changed, 7160 insertions(+), 5397 deletions(-)
 create mode 100644 lua/uuid.lua

你不需要看懂这些改动，只要知道：

上游在不断优化词库和功能；
你的 default.custom.yaml / squirrel.custom.yaml 不会被动；
输出末尾没有冲突提示，就是一次非常健康的 fast-forward 更新。

更新完再看一眼：

git status

只要还是：

nothing to commit, working tree clean

就可以认为当前状态是非常完美的：上游更新到最新，你的配置稳稳地叠在上面。

配置文件怎么改

鼠须管的默认配置文件在系统目录，不建议直接改。用户级配置应该用 *.custom.yaml 的形式覆盖/补丁。

常用的两个文件：

default.custom.yaml
- 控制 Rime 核心行为，例如按键绑定、候选数、启用的方案列表等。
squirrel.custom.yaml
- 只影响 macOS 前端，例如皮肤、每个 App 的默认中英文模式等。

基本原则：

使用 patch: 节点做“补丁”，不去手动编辑原来的 default.yaml、squirrel.yaml；
使用 "xxx/yyy/+" 的方式追加，而不是整块覆盖已有配置；
修改后要“重新部署”，否则不会生效。

可以简单理解为：

上游的 xxx.yaml 是“系统文件”；你的 xxx.custom.yaml 是“用户补丁层”。

WezTerm 里的三个坑

我的终端主力是 WezTerm，它是一个 GPU 渲染的终端模拟器，支持多平台。在 macOS 下配好鼠须管之后，遇到三个具体问题：

用 Shift 切换英文时，终端里会短暂残留拼音；
在终端类应用中，希望默认是英文模式，而不是上次状态；
小键盘回车和主键盘回车在输入法中的行为不一致。

下面分别说明处理方式。

说明：WezTerm 的安装和配置不在本文展开。简单说，就是一个独立安装的终端 App，Bundle ID 为 com.github.wez.wezterm，后面会在 Rime 配置里用到。

Shift 切换残留幽灵字符

8.1 现象

在 WezTerm 中处于中文输入状态，输入拼音，例如 ceshi；
按下 Shift 想切换到英文；
逻辑上拼音已经被清掉，但终端画面上依然显示 ceshi，直到再敲一个键才会消失。

这会给人一种“屏幕和实际状态不同步”的感觉。

8.2 思路

鼠须管中，Shift 键的行为可以配置。常见行为包括：

clear：清空预编辑区（不上屏）；
commit_code：把拼音原样作为英文上屏，然后切到英文；
noop：不做处理。

默认配置在有些终端里会出现渲染不同步。我的做法是把 Shift 行为改为 commit_code：

当前已输入的拼音直接上屏当英文字母；
同时切换到英文模式；
不再出现“残影”。

8.3 配置示例

编辑 ~/Library/Rime/default.custom.yaml，追加或修改：

patch:
  ascii_composer:
    good_old_caps_lock: true
    switch_key:
      Caps_Lock: clear      # 保持 Caps Lock 行为：清空并切换
      Shift_L: commit_code  # 左 Shift：上屏编码并切换到英文
      Shift_R: commit_code  # 右 Shift：同上
      Control_L: noop
      Control_R: noop

修改后：

保存文件；
鼠须管菜单 → “重新部署”；
在 WezTerm 中测试：输入拼音后按 Shift，应直接上屏为英文，并切换英文模式，屏幕不再残留。

让终端默认英文

9.1 需求

在终端和代码编辑器里，我更希望：

每次切到终端或编辑器时，默认使用英文；
在聊天软件、浏览器里可以保持上次状态或者默认中文。

Rime 支持按 App 设定不同的默认模式，靠的是应用的 Bundle ID。

9.2 查 Bundle ID

可以用 AppleScript 查询：

osascript -e 'id of app "WezTerm"'
# 输出类似：com.github.wez.wezterm

同理可以查 VSCode、iTerm2 等。

9.3 配置示例

编辑 ~/Library/Rime/squirrel.custom.yaml：

patch:
  app_options:
    # WezTerm 终端
    com.github.wez.wezterm:
      ascii_mode: true      # 默认英文

    # 其他常见开发工具（按需启用）
    com.microsoft.VSCode:
      ascii_mode: true
    com.googlecode.iterm2:
      ascii_mode: true

部署后：

切到 WezTerm 时，默认是英文输入；
切到 VSCode / iTerm2 等同理；
其他 App 不受影响。

小键盘回车行为不一致

10.1 现象

使用带小键盘的键盘时：

在拼音输入状态下，主键盘 Enter 可以把拼音原样上屏为英文（或完成候选）；
小键盘 Enter 的行为却不同，可能是清空、取消，或者不起作用。

Rime 里，这两个按键的键值不同：

主键盘回车：Return
小键盘回车：KP_Enter

10.2 目标

希望在“输入拼音时”（composing 状态）：

小键盘 KP_Enter 和 Return 行为一致；
即按下时，把当前内容按普通回车的逻辑处理。

10.3 配置示例

仍然是编辑 ~/Library/Rime/default.custom.yaml，在 patch: 下追加：

patch:
  # 前面可以有 ascii_composer 等配置

  "key_binder/bindings/+":
    - { accept: KP_Enter, send: Return, when: composing }

这里的含义是：

当输入法处于 composing 状态时（正在拼音输入，还没上屏）；
如果按下的键是 KP_Enter；
就把它当作 Return 处理。

部署后，小键盘回车和主键盘回车在输入法层面的行为就统一了。

常见问题

简单列几个我踩过或容易踩的点。

12.1 修改配置后没有效果

检查顺序：

保存文件时是否使用了 Tab 缩进（应使用空格）；
patch: 的缩进层级是否正确；
是否在鼠须管菜单中点击了“重新部署”，或者执行了前面那条带 --reload 的命令。

12.2 改错导致 Rime 无法部署

症状：

点击“重新部署”后，输入法闪一下，重新变回旧配置；
或者直接提示错误。

处理方法：

逐个检查最近修改的 *.custom.yaml；
可以借助命令行 YAML 校验工具（可选）；
实在不行，把本次改动先移走，确认恢复正常后再一段段加回来。

12.3 不确定某个 App 的 Bundle ID

使用 AppleScript：

osascript -e 'id of app "WezTerm"'
osascript -e 'id of app "Visual Studio Code"'

保证名字和 Launchpad 里显示的一致。

最后

折腾完之后，终端默认英文、Shift 不留残影、词库一行命令更新。日常用着确实舒服，就是第一次配的时候得有点耐心。

macOS 鼠须管配置：雾凇拼音安装、Git 词库管理与 WezTerm 兼容

Rime 和各平台前端

安装鼠须管

3.1 使用 Homebrew 安装（推荐）

3.2 输入法配置目录

引入雾凇拼音

4.1 手动方式（概念说明）

4.2 推荐方式：直接把 ~/Library/Rime 变成一个 Git 仓库

用 Git 管理词库

5.1 git status：个人配置为什么“看不见”？

5.2 更新词库的标准姿势

配置文件怎么改

WezTerm 里的三个坑

Shift 切换残留幽灵字符

8.1 现象

8.2 思路

8.3 配置示例

让终端默认英文

9.1 需求

9.2 查 Bundle ID

9.3 配置示例

小键盘回车行为不一致

10.1 现象

10.2 目标

10.3 配置示例

常见问题

12.1 修改配置后没有效果

12.2 改错导致 Rime 无法部署

12.3 不确定某个 App 的 Bundle ID

最后

评论

4.2 推荐方式：直接把 `~/Library/Rime` 变成一个 Git 仓库

5.1 `git status`：个人配置为什么“看不见”？