Espanso 标志 中文网

使用指南

十分钟完成安装，写出第一条扩展规则

这份指南按实际使用的顺序组织：先装好并确认运行，再认识配置文件，然后写第一条规则，最后处理常见问题。所有命令与路径均与官方文档一致，可直接照做。若还不确定这款工具是否适合你，先看文本扩展工具指南与工具对比。

安装与首次运行

Espanso 为三个桌面平台都提供了官方安装包。下载入口见 下载中心，也可以直接前往 GitHub Releases 获取。下表是各平台的系统要求与安装方式对照。

Windows
Windows 10 及以上，仅 x64；提供安装程序与便携版 zip
macOS
macOS 10.13 及以上，Intel 与 Apple Silicon 通用
Linux
区分 X11 与 Wayland 构建，提供 DEB 包与 AppImage
当前版本
v2.4.1（2026 年 9 月 2 日发布）

Windows

下载 Espanso-Win-Installer-x86_64.exe 双击安装，或使用便携版解压后运行其中的启动脚本。若首次运行时出现 SmartScreen 提示，点击「更多信息」后选择「仍要运行」即可——官方文档对此有明确说明。也可以用包管理器安装：

PowerShell 
winget install --id=Espanso.Espanso -e

macOS

下载 Espanso-Mac-Universal.dmg，打开后把应用拖入「应用程序」文件夹。也可以用 Homebrew：

Terminal 
brew install espanso

必须授予辅助功能权限。Espanso 需要监听键盘输入并向其他程序注入文本，因此要在「系统设置 → 隐私与安全性 → 辅助功能」中勾选它。未授权时程序会静默驻留但完全不工作，这是 macOS 上最常见的「装了没反应」原因。

Linux

先确认当前会话类型，再选择对应构建——X11 与 Wayland 版本不能混用。

Terminal 
# 查看当前会话类型：x11 或 wayland
echo $XDG_SESSION_TYPE

# Ubuntu / Debian：安装对应构建的 DEB 包
sudo apt install ./espanso-debian-x11-amd64.deb

# 注册为 systemd 服务并启动
espanso service register
espanso start

若使用 Wayland 构建，还需授予设备访问权限，否则无法读取键盘事件：

Terminal 
sudo setcap "cap_dac_override+p" $(which espanso)

该权限只在程序打开输入设备接口的瞬间生效，之后会立即自行清空，不需要以 root 身份长期运行。

验证是否安装成功

打开任意文本编辑器，输入 :espanso，如果出现 Hi there!，说明一切正常。这是安装包自带的示例规则。若没有反应，先在终端确认运行状态：

Terminal 
espanso status
espanso --version

配置文件结构

Espanso 采用文件化配置，遵循 Unix 式的设计思路：没有设置面板，所有参数都写在 YAML 文件里。初次安装后，配置目录的结构如下：

配置目录 
$CONFIG/
  config/
    default.yml      # 定义「怎么展开」：对所有程序生效的参数
  match/
    base.yml         # 定义「展开成什么」：你的片段库

两个目录的分工很清晰：match/ 决定内容，config/ 决定行为。配置目录的位置按平台不同：

平台 配置目录路径
Windows %APPDATA%\espanso
macOS ~/Library/Application Support/espanso
Linux ~/.config/espanso

不必记这些路径，执行下面的命令会直接告诉你实际位置，并可以用系统默认编辑器打开：

Terminal 
espanso path
espanso edit

配置目录默认是隐藏的。在 Windows 资源管理器或 macOS 访达中，可以把路径直接粘贴到地址栏跳转。

第一条匹配规则

打开 match/base.yml，你会看到一个已经存在的 matches: 段落。所有新规则都追加在这一段下面，注意保持两个空格一层缩进，并且不要使用制表符。

match/base.yml 
matches:
  # 安装包自带的示例，可保留也可删除
  - trigger: ":espanso"
    replace: "Hi there!"

  # 你的第一条规则：输入 :br 展开为签名
  - trigger: ":br"
    replace: "此致敬礼，\n张工 · 产品部\n138-0000-0000"

保存文件后不需要重启，Espanso 会自动检测变更并重新加载配置。切到任意输入框，键入 :br，就能看到签名段落出现。

规则可以复用与组合

随着片段变多，建议按主题拆分文件，例如 match/email.yml 放邮件话术、match/code.yml 放代码片段。再通过程序配置把对应的文件引入特定应用：

config/vscode.yml 
filter_title: "Visual Studio Code"

extra_includes:
  - "../match/_code_snippets.yml"

用变量让内容动态化

静态文本只是起点。加上 vars 后，同一段模板可以在每次展开时产生不同结果——插入当天日期、拼接剪贴板内容、调用脚本返回值。

match/base.yml 
  - trigger: ":stamp"
    replace: "[{{date}}] "
    vars:
      - name: date
        type: date
        params:
          format: "%Y-%m-%d %H:%M"

更多扩展类型（剪贴板、随机、选择、Shell、脚本、表单）的完整说明见 功能特性 页面；配置改错、触发不生效等具体问题的处理见 常见问题。

日常使用技巧

搜索栏：记不住触发词时的兜底

片段积累到几十条之后，很难记住每个触发词。按 Alt + Space（macOS 为 Option + Space）唤起搜索栏，输入关键词即可按描述找到片段并插入。在搜索栏中键入 > 开头的内容，还能显示控制与报告类命令。

退格撤销：误触发的后悔药

如果触发了不该展开的规则，展开后立刻按一次 Backspace，Espanso 会回退这次替换并恢复你原本输入的文字。这个行为可以通过在 config/default.yml 中设置 undo_backspace: false 关闭。

一键暂停：需要临时安静的时候

在写代码或玩游戏时，某些触发词可能带来干扰。可以通过状态栏图标菜单暂停 Espanso，也可以自定义一个开关快捷键，用一次按键在启用与暂停之间切换。

写好触发词的三条经验

  • 加前缀降低误触：用 :、; 等不常出现在词首的字符开头，例如 :addr、;sig。
  • 保持命名规律：按领域分组前缀，例如邮件类都用 :m-，代码类都用 :c-，几百条时依然好找。
  • 纠错类用整词匹配：把常见错拼做成自动纠正时，务必加上 word: true，否则会破坏包含该片段的正常单词。

常用命令速查

Espanso 提供命令行接口，用于管理服务、编辑配置、安装包与查看日志。以下命令在三个平台上通用。

命令 作用
espanso status 查看当前是否正在运行
espanso start / stop / restart 启动、停止或重启服务
espanso path 输出配置目录的绝对路径
espanso edit 用系统默认编辑器打开配置文件
espanso install <包名> 从 Espanso Hub 安装包
espanso package list 列出已安装的包
espanso log 查看运行日志，排查配置错误时最有用
espanso service register 注册为开机自启的系统服务（Linux 常用）

完整参数说明见官方文档的 Command-line reference。若命令提示找不到，说明可执行文件未加入 PATH，需要重新运行安装程序或手动配置环境变量。

常见问题

以下问题按实际求助频率排序，答案基于官方文档与项目行为说明整理。

不会。Espanso 的设计是本地优先：它没有账号体系，也不包含遥测或使用统计。触发词匹配与文本替换都在本机进程内完成，配置文件也保存在本地目录。你可以通过断网测试，或直接审查以 GPL-3.0 开源的源代码来验证这一点。

多数情况是系统辅助功能权限未授予。Espanso 需要监听键盘输入并向其他程序注入文本，必须在「系统设置 → 隐私与安全性 → 辅助功能」中勾选 Espanso。授权后建议完全退出并重新启动程序。

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

先在终端执行 echo $XDG_SESSION_TYPE 查看当前会话类型，输出 x11 就选 X11 构建，输出 wayland 就选 Wayland 构建，两者不能混用。

Wayland 版本在官方文档中标注为实验性支持，需要额外执行 setcap 授予权限，并且非美式键盘布局必须在配置中手动指定，否则替换的字符可能出错。

常见原因有三类。一是权限不对等：目标程序以管理员或 root 身份运行，而 Espanso 以普通用户权限运行，此时无法向高权限进程注入文本。二是程序使用了特殊的输入实现，可尝试为该程序单独设置 backend: clipboard。三是触发词与程序自身的快捷键冲突，建议改用带冒号前缀的触发词。

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

若无法定位，可把改动过的文件重命名备份，Espanso 会重新生成默认配置，然后把内容逐步迁回，每加一段保存一次以确定问题出在哪一段。建议把配置目录纳入 Git 版本管理，随时可以回滚。

支持。触发词本质是普通字符串，中文、标点与符号都可以作为触发词。需要注意的是，中文输入法在组合输入状态下可能拦截部分按键，建议用标点或符号作为触发词的前缀（例如「。dz」），并在目标程序中实际测试触发效果。

Espanso 本身不提供云端同步，官方建议把整个配置目录交给第三方同步工具管理，例如 Git 仓库、Syncthing 或网盘同步文件夹。由于配置是纯文本 YAML，用 Git 管理还能获得版本历史与冲突提示。

注意不要在多台机器上同时编辑同一份文件，否则同步工具会产生冲突副本，反而更难处理。

还没安装？先下载再照指南操作

安装包 5–19 MB，无需注册账号。装完用 :espanso 验证，之后就可以写自己的规则了。

前往下载中心