1. 写在前面横排变竖排的第一现场1.1 从升级到翻车的经过前几天把鼠须管从 1.11 升到 1.12当时想的很简单升个级能出什么问题。结果重启输入法之后候选词栏直接从横排变成了竖排一条一条往下列选词节奏彻底被打乱。当时我心里首先冒出来的念头是哪只软件都逃不过升级才有鬼的诅咒这种升级后功能退步的场景实在太像历史重演了。第一反应是配置被升级过程重置了赶紧打开~/Library/Rime/squirrel.custom.yaml结果style/horizontal: true这行原封不动地躺在那里。那就重新部署一次吧点完菜单栏鼠须管图标里的重新部署候选词依然是竖排。退出输入法再打开竖排还是竖排。那一刻我是真有点上头。1.2 这篇内容适合谁看后来在社区里一搜发现这不是我一个人遇到的情况1.12 版本之后候选词横排设置失效的反馈并不少。问题本身不算复杂但坑点在于它的表现很像配置被重置了实际上却是新版对候选窗布局的配置解析方式发生了变化导致旧的横排开关不再被当作唯一依据。这篇文章会把我的排查过程和解决办法完整记录下来。如果你升级后也遇到横排变竖排、横排设置不生效可以直接跳到第 3 节按步骤操作如果你想顺手把原理也弄清楚建议从第 2 节开始读。文中涉及的文件路径都是 macOS 下的默认路径鼠须管对应英文名 Squirrel下面的内容默认你已经装上并在用这款输入法。2. 为什么一个没动过的配置会突然失效2.1 鼠须管的配置文件到底有哪几份鼠须管是 Rime 输入法引擎在 macOS 上的前端它的所有配置都是纯文本 YAML 文件放在~/Library/Rime/目录里。和候选词外观直接相关的主要是下面这几份default.yaml引擎层全局配置。候选词数量、翻页快捷键、方案列表都在这里里面也有一个 style 组但一般不建议直接改它来做外观定制。squirrel.yamlSquirrel 前端专属的外观配置。字体、字号、配色方案、候选窗的横排竖排都归这个文件管。squirrel.custom.yamlsquirrel.yaml 的用户补丁文件也是官方最推荐的修改入口。个人定制写到这个文件里部署时通过 patch 指令合并进主配置。这三者的关系可以理解成default.yaml是出厂默认值squirrel.yaml是前端外观模板squirrel.custom.yaml是你自己打的补丁补丁的优先级最高。部署时 Rime 把三份配置按顺序合并生成最终生效的配置再交给前端渲染候选窗。如果你之前是从网上抄的配置很可能只关注了把文件放在哪里没太注意这个分层合并的机制。很多改了没反应的问题根源就在改错了文件——改到了default.yaml或者某个具体输入方案的.custom.yaml里而那个文件的配置级别和加载顺序跟你预期的并不一样。2.2 patch 补丁机制改配置的正确姿势patch是 Rime 配置体系里最核心的机制。它允许你不改动主配置文件而是在一个独立的.custom.yaml文件里指定我要覆盖哪个键的哪个值。最基础写法如下patch: style/horizontal: true这里的斜杠表示层级路径style/horizontal等价于style 组下面的 horizontal 字段。部署时Rime 会把这条补丁合并到主配置里最终生成的配置里style.horizontal就是true。除了斜杠写法也可以写成嵌套 map 的形式patch: style: horizontal: true两种写法在绝大多数版本里都支持但如果你一个文件里左边用斜杠式、右边用嵌套式缩进又没对齐很容易出现部分生效、部分被忽略的玄学问题。我的建议是一个文件里统一用一种写法别混着来。提示patch 块的键路径一旦写错Rime 不会报任何错只会安静地忽略它。这是很多配置没生效问题的真正元凶排查时优先检查这里。2.3 1.12 版本里候选窗布局的解析变化这次我遇到的情况显然不是写法问题因为我升级前配置一直是好的文件内容也没动过。那问题出在哪结合 1.12 版本的更新内容和社区反馈可以基本确定两件事第一1.12 对候选窗布局的配置项做了一个重要调整。旧版本里候选词是横排还是竖排主要看style.horizontal这个布尔值新版本引入了更完整的候选列表布局配置candidate_list_layout用字符串来控制横排、竖排等不同的排布方式。如果你只写了旧键horizontal: true新版解析时可能不会把它当作唯一的横排开关于是候选窗就回落到默认的竖排布局。第二很多人在升级后没有重新部署或者只是把鼠须管退出再打开导致新版没有用重新合并后的配置去生成候选窗。在 1.12 里仅重启应用不一定会重新读取配置文件必须走一遍完整的部署流程。这两个原因叠加在一起就出现了设置明明还在但候选词就是竖排的诡异现象。下面直接上实操修复步骤。3. 实操修复把横排重新找回来3.1 备份与现状检查改配置之前先把当前的squirrel.custom.yaml备份一份防止改崩了找不回原样cp ~/Library/Rime/squirrel.custom.yaml ~/Library/Rime/squirrel.custom.yaml.bak这个习惯非常重要。鼠须管的 YAML 配置对缩进和语法很敏感一个非法字符就可能让整个配置失效备份能让你在十秒内回到可用状态。备份完先看一眼现在文件里到底写了什么cat ~/Library/Rime/squirrel.custom.yaml重点看 patch 块下有没有style/horizontal以及它所在的层级。顺便确认文件里是不是只有一份 patch 块。很多人复制网上配置时会不小心粘出两份 patch后者会把前者覆盖掉这种低级错误造成的失效比想象中常见得多。3.2 写入新旧两个布局键推荐的做法是在原有horizontal的基础上加上新键两者同时写上提高兼容性patch: style/horizontal: true style/candidate_list_layout: linear如果你的版本里candidate_list_layout取linear后没反应可以试试只保留horizontal: true部署后观察效果。因为 1.12 之后的各个小版本对这两个键的兼容优先级不完全一致实际测试哪种写法在你的版本上有效就用哪种。如果你现有的配置文件里还有font_face、color_scheme等其它设置保持它们不动只调整布局相关的两行即可。要特别注意的是别把整个patch:块用网上的配置整段替换那样会把之前调好的字体、配色全部冲掉。3.3 重新部署与验证配置改完必须重新部署才能真正生效。操作方式点击菜单栏上的鼠须管图标选择重新部署。部署过程中输入法会短暂消失或者候选窗重新出现这是正常现象耐心等几秒。部署完成后随手打个拼音看候选词是不是已经横排。如果还是竖排不要急着改文件先做一次彻底重启在系统设置里把鼠须管关闭再打开或者干脆注销当前用户重新登录。这个操作能强制 Squirrel 重新初始化整个输入法进程很多部署后仍然不刷新的问题都能靠这一步解决。注意只退出鼠须管再打开不保证会重新读取合并后的配置。必须以重新部署为准部署后再做一次进程级重启才算完整的生效流程。3.4 兜底回退到旧版本如果新版跟你就是不兼容横排始终调不回来最直接的兜底方案是回退到 1.11.x。使用 Homebrew 可以安装指定版本如果本机还留着旧版本缓存的话brew install --cask squirrel如果已经装好了新版先卸载再装旧版本。或者去项目 GitHub Releases 页面手动下载旧版的 .dmg 安装包安装前记得把新版完整退出。回退后把squirrel.custom.yaml里的新键值删掉恢复成纯horizontal: true的写法横排大概率就回来了。4. 更深入的排查设置失效的四个隐藏推手4.1 YAML 语法问题缩进、引号、布尔值YAML 是个看着简单、坑起来要命的东西。鼠须管配置里最常见的三类语法错误用了 Tab 缩进而不是空格。YAML 标准里 Tab 是禁止的鼠须管解析时可能直接忽略整段配置。布尔值被加了引号。true是布尔值true是字符串两者在 Rime 眼里是完全不同的东西。写成horizontal: true它就不会被当作开关来生效。键值之间的冒号后面必须有空格。style:horizontal是错的style: horizontal才对。想快速验证 YAML 语法可以用系统自带的 python3 做一次解析python3 - EOF import yaml with open(/Users/你的用户名/Library/Rime/squirrel.custom.yaml) as f: print(yaml.safe_load(f)) EOF如果这段代码正常打印出字典结构说明 YAML 语法没毛病如果抛出异常它会明确告诉你问题出在第几行。这是我在排查各种配置失效问题时最常用的工具比肉眼盯着缩进靠谱得多。4.2 多个配置文件互相覆盖鼠须管读取配置是分层合并的default.yaml、squirrel.yaml、squirrel.custom.yaml以及每个输入方案自己的.custom.yaml都会参与合并。假如你在default.custom.yaml里也写过style/horizontal: false那么即使squirrel.custom.yaml里是true最终合并结果也可能被覆盖掉。排查办法打开~/Library/Rime/build/目录里面存的是部署后生成的最终配置。找到对应的合并产物搜索horizontal和candidate_list_layout这两个键看看最终值到底是什么。这一步能直接定位到底是谁覆盖了谁比瞎猜有效率得多。4.3 build 目录缓存异常build目录里存的是 Rime 编译后的最终配置缓存。有时升级后旧缓存没有正确清理新配置没有被重新编译进去就会出现源文件改了实际却一直用旧配置的情况。处理方式并不复杂把build目录里和 squirrel 相关的缓存文件删掉然后重新部署一次。Rime 会重新读取所有源配置重新生成缓存。删之前建议整体备份一下build目录虽然它理论上可以重建但小心驶得万年船。4.4 主题配色方案覆盖样式有些配色方案color_scheme里可以自带候选窗布局参数当你切换了某个主题主题内的布局设置可能覆盖全局的 style 设置。这也是横排设置莫名其妙失效的高频原因之一尤其是你从社区下载了第三方主题的时候。如果你用了第三方配色主题可以在主题对应的 YAML 文件里搜索horizontal或candidate_list_layout把它们删掉或者改成与全局设置一致的布局这样候选窗的排布方式就完全由你主配置里的 style 决定了。别小看这个细节很多主题作者会顺手带上布局设置你自己调了半天全局配置结果一直被主题压着。4.5 最后手段彻底重置配置如果上面的排查全部做完还是不行配置文件已经被改得千疮百孔那就走最后一步把~/Library/Rime目录整体复制一份备份然后清空这个目录重新部署。Squirrel 会生成一份全新的默认配置输入法恢复出厂状态。恢复之后再把你真正需要的定制逐条加回去每次只加一项部署一次验证一次。这种方式看起来笨但能保证每一步的变更都可控很多反复折腾不出来的问题到最后都是用这招解决的。我自己遇到疑难杂症时宁可重置再逐步加也不愿意在一个已经被改乱的文件里继续打补丁。5. 常见问题速查与避坑心得5.1 症状、原因、对策速查表现象可能原因解决办法升级 1.12 后候选词变竖排新版本候选窗布局键变更在配置中加入style/candidate_list_layout: linear并重新部署重新部署后仍然竖排输入法进程没有完全重启注销当前用户重新登录或彻底退出再打开鼠须管补丁完全没生效patch 路径写错或 YAML 缩进错误用 python3 校验 YAML检查键路径是否带style/前缀只有部分配置生效多个 custom 文件互相覆盖检查 build 目录里的最终合并配置定位覆盖来源切换主题后横排变竖排主题文件内置布局参数修改主题文件或换回默认主题部署时报错配置中存在非法字符或 Tab 缩进回滚备份逐段排查一次改动一项这张表是我在实际排查中反复用到的对照思路。遇到问题先对号入座比从头翻文档快很多。5.2 几条用实际操作换来的建议第一每次改配置前复制一份.bak文件这个习惯能救你无数次。第二改完配置永远走一遍重新部署不要只退出重开输入法。第三从网上抄配置时一行一行看清楚再粘尤其注意缩进到底是空格还是 Tab。第四尽量不要在一个文件里混用斜杠写法和嵌套写法选一种统一用到底。第五升级大版本前先翻一眼 release notes看看有没有 breaking change而不是升完再被问题追着跑。这些心得都是我在实际使用中一点点攒出来的。鼠须管的可玩性很高但配置体系确实有学习成本遇到问题别急着卸载重装按上面的排查路径一步步来九成以上的配置问题都能自己解决。我个人最后的体会是输入法配置这事儿心越急越容易出错。慢下来先把配置文件结构看明白再动每一行效率反而最高。
鼠须管升级1.12后候选词横排失效？排查与修复指南
1. 写在前面横排变竖排的第一现场1.1 从升级到翻车的经过前几天把鼠须管从 1.11 升到 1.12当时想的很简单升个级能出什么问题。结果重启输入法之后候选词栏直接从横排变成了竖排一条一条往下列选词节奏彻底被打乱。当时我心里首先冒出来的念头是哪只软件都逃不过升级才有鬼的诅咒这种升级后功能退步的场景实在太像历史重演了。第一反应是配置被升级过程重置了赶紧打开~/Library/Rime/squirrel.custom.yaml结果style/horizontal: true这行原封不动地躺在那里。那就重新部署一次吧点完菜单栏鼠须管图标里的重新部署候选词依然是竖排。退出输入法再打开竖排还是竖排。那一刻我是真有点上头。1.2 这篇内容适合谁看后来在社区里一搜发现这不是我一个人遇到的情况1.12 版本之后候选词横排设置失效的反馈并不少。问题本身不算复杂但坑点在于它的表现很像配置被重置了实际上却是新版对候选窗布局的配置解析方式发生了变化导致旧的横排开关不再被当作唯一依据。这篇文章会把我的排查过程和解决办法完整记录下来。如果你升级后也遇到横排变竖排、横排设置不生效可以直接跳到第 3 节按步骤操作如果你想顺手把原理也弄清楚建议从第 2 节开始读。文中涉及的文件路径都是 macOS 下的默认路径鼠须管对应英文名 Squirrel下面的内容默认你已经装上并在用这款输入法。2. 为什么一个没动过的配置会突然失效2.1 鼠须管的配置文件到底有哪几份鼠须管是 Rime 输入法引擎在 macOS 上的前端它的所有配置都是纯文本 YAML 文件放在~/Library/Rime/目录里。和候选词外观直接相关的主要是下面这几份default.yaml引擎层全局配置。候选词数量、翻页快捷键、方案列表都在这里里面也有一个 style 组但一般不建议直接改它来做外观定制。squirrel.yamlSquirrel 前端专属的外观配置。字体、字号、配色方案、候选窗的横排竖排都归这个文件管。squirrel.custom.yamlsquirrel.yaml 的用户补丁文件也是官方最推荐的修改入口。个人定制写到这个文件里部署时通过 patch 指令合并进主配置。这三者的关系可以理解成default.yaml是出厂默认值squirrel.yaml是前端外观模板squirrel.custom.yaml是你自己打的补丁补丁的优先级最高。部署时 Rime 把三份配置按顺序合并生成最终生效的配置再交给前端渲染候选窗。如果你之前是从网上抄的配置很可能只关注了把文件放在哪里没太注意这个分层合并的机制。很多改了没反应的问题根源就在改错了文件——改到了default.yaml或者某个具体输入方案的.custom.yaml里而那个文件的配置级别和加载顺序跟你预期的并不一样。2.2 patch 补丁机制改配置的正确姿势patch是 Rime 配置体系里最核心的机制。它允许你不改动主配置文件而是在一个独立的.custom.yaml文件里指定我要覆盖哪个键的哪个值。最基础写法如下patch: style/horizontal: true这里的斜杠表示层级路径style/horizontal等价于style 组下面的 horizontal 字段。部署时Rime 会把这条补丁合并到主配置里最终生成的配置里style.horizontal就是true。除了斜杠写法也可以写成嵌套 map 的形式patch: style: horizontal: true两种写法在绝大多数版本里都支持但如果你一个文件里左边用斜杠式、右边用嵌套式缩进又没对齐很容易出现部分生效、部分被忽略的玄学问题。我的建议是一个文件里统一用一种写法别混着来。提示patch 块的键路径一旦写错Rime 不会报任何错只会安静地忽略它。这是很多配置没生效问题的真正元凶排查时优先检查这里。2.3 1.12 版本里候选窗布局的解析变化这次我遇到的情况显然不是写法问题因为我升级前配置一直是好的文件内容也没动过。那问题出在哪结合 1.12 版本的更新内容和社区反馈可以基本确定两件事第一1.12 对候选窗布局的配置项做了一个重要调整。旧版本里候选词是横排还是竖排主要看style.horizontal这个布尔值新版本引入了更完整的候选列表布局配置candidate_list_layout用字符串来控制横排、竖排等不同的排布方式。如果你只写了旧键horizontal: true新版解析时可能不会把它当作唯一的横排开关于是候选窗就回落到默认的竖排布局。第二很多人在升级后没有重新部署或者只是把鼠须管退出再打开导致新版没有用重新合并后的配置去生成候选窗。在 1.12 里仅重启应用不一定会重新读取配置文件必须走一遍完整的部署流程。这两个原因叠加在一起就出现了设置明明还在但候选词就是竖排的诡异现象。下面直接上实操修复步骤。3. 实操修复把横排重新找回来3.1 备份与现状检查改配置之前先把当前的squirrel.custom.yaml备份一份防止改崩了找不回原样cp ~/Library/Rime/squirrel.custom.yaml ~/Library/Rime/squirrel.custom.yaml.bak这个习惯非常重要。鼠须管的 YAML 配置对缩进和语法很敏感一个非法字符就可能让整个配置失效备份能让你在十秒内回到可用状态。备份完先看一眼现在文件里到底写了什么cat ~/Library/Rime/squirrel.custom.yaml重点看 patch 块下有没有style/horizontal以及它所在的层级。顺便确认文件里是不是只有一份 patch 块。很多人复制网上配置时会不小心粘出两份 patch后者会把前者覆盖掉这种低级错误造成的失效比想象中常见得多。3.2 写入新旧两个布局键推荐的做法是在原有horizontal的基础上加上新键两者同时写上提高兼容性patch: style/horizontal: true style/candidate_list_layout: linear如果你的版本里candidate_list_layout取linear后没反应可以试试只保留horizontal: true部署后观察效果。因为 1.12 之后的各个小版本对这两个键的兼容优先级不完全一致实际测试哪种写法在你的版本上有效就用哪种。如果你现有的配置文件里还有font_face、color_scheme等其它设置保持它们不动只调整布局相关的两行即可。要特别注意的是别把整个patch:块用网上的配置整段替换那样会把之前调好的字体、配色全部冲掉。3.3 重新部署与验证配置改完必须重新部署才能真正生效。操作方式点击菜单栏上的鼠须管图标选择重新部署。部署过程中输入法会短暂消失或者候选窗重新出现这是正常现象耐心等几秒。部署完成后随手打个拼音看候选词是不是已经横排。如果还是竖排不要急着改文件先做一次彻底重启在系统设置里把鼠须管关闭再打开或者干脆注销当前用户重新登录。这个操作能强制 Squirrel 重新初始化整个输入法进程很多部署后仍然不刷新的问题都能靠这一步解决。注意只退出鼠须管再打开不保证会重新读取合并后的配置。必须以重新部署为准部署后再做一次进程级重启才算完整的生效流程。3.4 兜底回退到旧版本如果新版跟你就是不兼容横排始终调不回来最直接的兜底方案是回退到 1.11.x。使用 Homebrew 可以安装指定版本如果本机还留着旧版本缓存的话brew install --cask squirrel如果已经装好了新版先卸载再装旧版本。或者去项目 GitHub Releases 页面手动下载旧版的 .dmg 安装包安装前记得把新版完整退出。回退后把squirrel.custom.yaml里的新键值删掉恢复成纯horizontal: true的写法横排大概率就回来了。4. 更深入的排查设置失效的四个隐藏推手4.1 YAML 语法问题缩进、引号、布尔值YAML 是个看着简单、坑起来要命的东西。鼠须管配置里最常见的三类语法错误用了 Tab 缩进而不是空格。YAML 标准里 Tab 是禁止的鼠须管解析时可能直接忽略整段配置。布尔值被加了引号。true是布尔值true是字符串两者在 Rime 眼里是完全不同的东西。写成horizontal: true它就不会被当作开关来生效。键值之间的冒号后面必须有空格。style:horizontal是错的style: horizontal才对。想快速验证 YAML 语法可以用系统自带的 python3 做一次解析python3 - EOF import yaml with open(/Users/你的用户名/Library/Rime/squirrel.custom.yaml) as f: print(yaml.safe_load(f)) EOF如果这段代码正常打印出字典结构说明 YAML 语法没毛病如果抛出异常它会明确告诉你问题出在第几行。这是我在排查各种配置失效问题时最常用的工具比肉眼盯着缩进靠谱得多。4.2 多个配置文件互相覆盖鼠须管读取配置是分层合并的default.yaml、squirrel.yaml、squirrel.custom.yaml以及每个输入方案自己的.custom.yaml都会参与合并。假如你在default.custom.yaml里也写过style/horizontal: false那么即使squirrel.custom.yaml里是true最终合并结果也可能被覆盖掉。排查办法打开~/Library/Rime/build/目录里面存的是部署后生成的最终配置。找到对应的合并产物搜索horizontal和candidate_list_layout这两个键看看最终值到底是什么。这一步能直接定位到底是谁覆盖了谁比瞎猜有效率得多。4.3 build 目录缓存异常build目录里存的是 Rime 编译后的最终配置缓存。有时升级后旧缓存没有正确清理新配置没有被重新编译进去就会出现源文件改了实际却一直用旧配置的情况。处理方式并不复杂把build目录里和 squirrel 相关的缓存文件删掉然后重新部署一次。Rime 会重新读取所有源配置重新生成缓存。删之前建议整体备份一下build目录虽然它理论上可以重建但小心驶得万年船。4.4 主题配色方案覆盖样式有些配色方案color_scheme里可以自带候选窗布局参数当你切换了某个主题主题内的布局设置可能覆盖全局的 style 设置。这也是横排设置莫名其妙失效的高频原因之一尤其是你从社区下载了第三方主题的时候。如果你用了第三方配色主题可以在主题对应的 YAML 文件里搜索horizontal或candidate_list_layout把它们删掉或者改成与全局设置一致的布局这样候选窗的排布方式就完全由你主配置里的 style 决定了。别小看这个细节很多主题作者会顺手带上布局设置你自己调了半天全局配置结果一直被主题压着。4.5 最后手段彻底重置配置如果上面的排查全部做完还是不行配置文件已经被改得千疮百孔那就走最后一步把~/Library/Rime目录整体复制一份备份然后清空这个目录重新部署。Squirrel 会生成一份全新的默认配置输入法恢复出厂状态。恢复之后再把你真正需要的定制逐条加回去每次只加一项部署一次验证一次。这种方式看起来笨但能保证每一步的变更都可控很多反复折腾不出来的问题到最后都是用这招解决的。我自己遇到疑难杂症时宁可重置再逐步加也不愿意在一个已经被改乱的文件里继续打补丁。5. 常见问题速查与避坑心得5.1 症状、原因、对策速查表现象可能原因解决办法升级 1.12 后候选词变竖排新版本候选窗布局键变更在配置中加入style/candidate_list_layout: linear并重新部署重新部署后仍然竖排输入法进程没有完全重启注销当前用户重新登录或彻底退出再打开鼠须管补丁完全没生效patch 路径写错或 YAML 缩进错误用 python3 校验 YAML检查键路径是否带style/前缀只有部分配置生效多个 custom 文件互相覆盖检查 build 目录里的最终合并配置定位覆盖来源切换主题后横排变竖排主题文件内置布局参数修改主题文件或换回默认主题部署时报错配置中存在非法字符或 Tab 缩进回滚备份逐段排查一次改动一项这张表是我在实际排查中反复用到的对照思路。遇到问题先对号入座比从头翻文档快很多。5.2 几条用实际操作换来的建议第一每次改配置前复制一份.bak文件这个习惯能救你无数次。第二改完配置永远走一遍重新部署不要只退出重开输入法。第三从网上抄配置时一行一行看清楚再粘尤其注意缩进到底是空格还是 Tab。第四尽量不要在一个文件里混用斜杠写法和嵌套写法选一种统一用到底。第五升级大版本前先翻一眼 release notes看看有没有 breaking change而不是升完再被问题追着跑。这些心得都是我在实际使用中一点点攒出来的。鼠须管的可玩性很高但配置体系确实有学习成本遇到问题别急着卸载重装按上面的排查路径一步步来九成以上的配置问题都能自己解决。我个人最后的体会是输入法配置这事儿心越急越容易出错。慢下来先把配置文件结构看明白再动每一行效率反而最高。
