Espanso 常见问题解答

完全免费。Espanso 以 GPL-3.0 协议开源，全部功能无试用期、无功能限制、无需激活，也不需要注册账号。

项目接受自愿捐赠，但捐赠与使用权限无关。你可以在 GitHub Releases 页面直接下载全部安装包。

不会。Espanso 采用本地优先架构：没有账号体系，不包含遥测或使用统计，触发词匹配与文本替换都在本机进程内完成，配置文件也保存在本地目录。

这一点可以自行验证：断开网络后功能不受影响；代码以 GPL-3.0 开源，任何人都能审查它是否发起网络请求。需要注意的是，「本地处理」不等于「无权限」——它仍需监听键盘才能工作，这是功能所需。

当前稳定版 v2.4.1 的安装包体积：Linux DEB 约 4.6 MB，Windows 安装程序约 7.0 MB，便携版约 7.4 MB，macOS 通用镜像约 16 MB，Linux AppImage 约 19 MB。

系统要求：Windows 10 及以上（仅 x64 架构）、macOS 10.13 及以上（Intel 与 Apple Silicon 通用）、Linux 需区分 X11 与 Wayland。Windows ARM 版本尚未提供，官方仍在计划中。

目前没有面向普通用户的完整图形界面，配置以文件为主。官方文档说明图形界面仍在规划中。

这既是门槛也是特性：上手需要理解 YAML 缩进规则，但配置可纳入版本管理、可批量生成、可团队共享。如果完全不希望接触配置文件，图形界面类工具会更合适，对比见 工具对比。

不支持。Espanso 仅面向桌面系统，没有 iOS 或 Android 版本。官方列出的平台是 Windows、macOS 与 Linux。

如果需要在移动端使用类似能力，可考虑系统自带的文本替换功能——iOS 与 macOS 的「文本替换」可通过 iCloud 在设备间同步静态短语。

最可能是辅助功能权限未授予。Espanso 需要监听键盘输入并向其他程序注入文本，必须在「系统设置 → 隐私与安全性 → 辅助功能」中勾选 Espanso。

授权后建议完全退出程序再重新启动。未授权时 Espanso 会静默驻留但不工作，也不会有任何报错提示，所以很容易误判为安装失败。

若首次打开时提示来自未识别的开发者，可在「隐私与安全性」页面点击「仍要打开」，系统会记住这个选择。

先在终端执行 echo $XDG_SESSION_TYPE 查看当前会话类型。输出 x11 就选 X11 构建，输出 wayland 就选 Wayland 构建，两者不能混用，装错会直接失效且难以排查。

Wayland 版本在官方文档中标注为实验性支持，需要额外执行 sudo setcap "cap_dac_override+p" $(which espanso) 授予设备访问权限；非美式键盘布局还必须在配置中手动指定，否则替换的字符可能出错。

常见原因有三类。一是权限不对等：目标程序以管理员或 root 身份运行，而 Espanso 以普通用户权限运行，此时无法向高权限进程注入文本。

二是程序使用了特殊的输入实现，可以尝试为该程序单独设置 backend: clipboard，改用剪贴板方式写入。

三是触发词与程序自身的快捷键冲突，建议改用带冒号前缀的触发词。排查时先用记事本或文本编辑测试，确认配置本身没问题，再逐步定位到具体程序。

YAML 对缩进极为敏感，最常见的问题是混用了制表符或层级错位。先执行 espanso log 查看错误日志定位行号，再执行 espanso restart 重新加载。

若无法定位，可把改动过的文件重命名备份，Espanso 会重新生成默认配置，然后把内容分段迁回，每加一段保存一次以确定问题出在哪一段。

建议把整个配置目录纳入 Git 版本管理，这样改错时可以直接回滚，也便于在多台设备间同步。

支持。触发词本质是普通字符串，中文、标点与符号都可以作为触发词，例如把「。dz」映射为完整地址。

需要注意的是，中文输入法在组合输入状态下可能拦截部分按键，建议用标点或符号作为触发词的前缀，避开拼音候选阶段，并在实际使用的程序中测试触发效果。

Espanso 本身不提供云端同步。官方建议把整个配置目录交给第三方工具管理，例如 Git 仓库、Syncthing 或网盘同步文件夹。

由于配置是纯文本 YAML，用 Git 管理还能获得版本历史与冲突提示。注意不要在多台机器上同时编辑同一份文件，否则同步工具会产生冲突副本，反而更难处理。

输入法的自定义短语通常只支持静态文本，内容长度受候选栏限制，且依赖输入法处于特定状态；Espanso 是系统级工具，支持多行文本、图片、日期、表单与脚本，且不受输入法切换影响。

两者并不冲突。日常几个固定短句用输入法就够了；需要结构化的长内容或动态内容时，用专门的文本扩展工具更合适。详细对比见 文本扩展工具指南。

Windows 可在「设置 → 应用」中卸载，或重新运行安装程序选择卸载；若曾使用便携版，删除解压目录并移除开机启动项即可。

macOS 将应用从「应用程序」文件夹移到废纸篓，并建议在「系统设置 → 隐私与安全性 → 辅助功能」中移除对应条目。Linux 若通过 DEB 安装，执行 sudo apt remove espanso；若曾注册为服务，先执行 espanso service unregister。

配置文件目录默认不会被删除，如需彻底清理请手动删除配置目录。卸载前建议先备份配置。

不建议。配置文件是普通文本文件，不是加密存储，任何能访问该文件的程序或人员都能读到内容。

密码、短信验证码、身份证号、银行卡号、私钥与 API 密钥都不应写进片段库，这类信息请使用专业的密码管理器。同理，来源不明的社区包与脚本也应当先审查内容再决定是否安装，因为它们可能执行本机命令。