espanso 文本扩展工具¶

一句话概述：espanso 是跨平台的文本扩展工具，输入缩写自动替换为完整文本，省去重复打字，支持 Linux/macOS/Windows。

核心知识点¶

概念	白话解释
espanso	文本扩展器 = 输入缩写自动变长文本
Trigger	触发词 = 你输入的缩写（如 `:email`）
Replace	替换内容 = 缩写展开后的完整文本
Match	匹配规则 = 一条触发词→替换内容的规则
Package	包 = 社区共享的规则集

安装配置¶

# Linux（Snap）
sudo snap install espanso --classic                    # Snap 安装

# Linux（源码 / AppImage）
# 从 https://espanso.org/install/ 下载

# macOS
brew install espanso                                   # Homebrew

# Windows
# 从官网下载安装包

# 启动
espanso start                                         # 启动后台服务
espanso status                                        # 查看状态

配置文件¶

# 配置文件位置：
# Linux:   ~/.config/espanso/match/base.yml
# macOS:   ~/Library/Application Support/espanso/match/base.yml
# 或运行: espanso path → 查看路径

# ~/.config/espanso/match/base.yml

matches:
  # 基本替换
  - trigger: ":email"                                  # 输入 :email
    replace: "pengwenqiang@example.com"                # 替换为邮箱

  - trigger: ":addr"                                   # 输入 :addr
    replace: "XX大学生命科学学院"                         # 替换为地址

  - trigger: ":sig"                                    # 输入 :sig
    replace: |                                         # 多行文本
      祝好！
      彭文强
      XX大学

  # 日期时间（动态变量）
  - trigger: ":date"                                   # 输入 :date
    replace: "{{today}}"                               # 替换为今天日期
    vars:
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"                           # 格式：2026-05-13

  - trigger: ":now"                                    # 输入 :now
    replace: "{{time}}"
    vars:
      - name: time
        type: date
        params:
          format: "%Y-%m-%d %H:%M:%S"                  # 带时间

  # 生信常用
  - trigger: ":fas"                                    # FASTQ 质控命令
    replace: "fastp -i {{input}} -o clean_{{input}} -h report.html -j report.json"

  - trigger: ":conda"                                  # conda 激活
    replace: "conda activate {{env}}"
    vars:
      - name: env
        type: choice                                   # 弹出选择框
        params:
          values:
            - bioinfo
            - t2d_ml
            - qc_tools

  # 代码片段
  - trigger: ":pyhead"                                 # Python 文件头
    replace: |
      #!/usr/bin/env python3
      # -*- coding: utf-8 -*-
      """
      Description: {{description}}
      Author: 彭文强
      Date: {{today}}
      """

      import argparse
      import logging
    vars:
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"
      - name: description
        type: echo
        params:
          echo: ""                                     # 需要手动填写

  # Shell 常用
  - trigger: ":shhead"                                 # Shell 脚本头
    replace: |
      #!/bin/bash
      set -euo pipefail                                # 严格模式
      # Description: {{clipboard}}
      # Author: 彭文强
      # Date: {{today}}
    vars:
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"
      - name: clipboard
        type: clipboard                                # 粘贴剪贴板内容

安装社区包¶

# 浏览包：https://hub.espanso.org
espanso install all-emojis                             # 安装 emoji 包
espanso install lorem                                  # 安装 Lorem Ipsum 包

# 使用
# 输入 :joy: → 😂
# 输入 :lorem → 生成假文本

常见报错¶

报错	原因	解决
espanso 不触发	服务未启动	`espanso start`
YAML 解析错误	缩进错误	检查 YAML 缩进（用空格，不用 Tab）
权限问题（macOS）	未授权辅助功能	系统设置 → 隐私 → 辅助功能 → 勾选 espanso
权限问题（Linux）	X11/Wayland 兼容	检查 espanso 的 backend 设置

速查表¶

# 命令
espanso start                                         # 启动
espanso stop                                          # 停止
espanso restart                                       # 重启
espanso status                                        # 状态
espanso path                                          # 查看配置路径
espanso edit                                          # 编辑配置文件
espanso install <pkg>                                 # 安装社区包

# 变量类型
# date     → 日期时间
# clipboard → 剪贴板内容
# choice   → 弹出选择框
# echo     → 固定值
# shell    → 执行命令并使用输出
# random   → 随机值

# 触发词命名建议
# 用冒号开头：:email :date :sig
# 分类前缀：:bio-fastp :py-head :sh-loop