第 13 章：补全系统
第 13 章：补全系统
13.1 补全系统概览
Emacs 的补全系统分为两个层面：
- Minibuffer 补全：命令执行、文件打开、缓冲区切换等
- 代码补全：编程时的代码补全
现代补全方案对比
| 方案 | 定位 | 风格 | 特点 |
|---|---|---|---|
| Vertico + Corfu | 模块化 | 精简 | Emacs 29+ 推荐，最小依赖 |
| Ivy/Counsel/Swiper | 一体化 | 功能丰富 | 成熟稳定，开箱即用 |
| Helm | 一体化 | 功能极丰富 | 功能最强但较重 |
| Ido | 内置 | 简单 | Emacs 内置，无需安装 |
| Icomplete | 内置 | 简单 | Emacs 内置，类 Vertico |
Vertico vs Ivy vs Helm
| 特性 | Vertico | Ivy | Helm |
|---|---|---|---|
| 包数量 | 4+ | 3 | 1（大包） |
| 配置复杂度 | 低 | 中 | 高 |
| 性能 | 极快 | 快 | 中 |
| 可扩展性 | 高 | 中 | 中 |
| 学习曲线 | 低 | 中 | 高 |
| 内存占用 | 极少 | 少 | 较多 |
| 社区活跃度 | 高 | 高 | 中 |
13.2 Vertico（Minibuffer 补全）
Vertico 是一个极简的 Minibuffer 补全 UI。
安装配置
;; 核心包
(use-package vertico
:init
(vertico-mode 1)
:config
(setq vertico-count 15
vertico-resize t
vertico-cycle t))
;; 持久化（重启后保留历史）
(use-package savehist
:init
(savehist-mode 1))
Vertico 操作
| 按键 | 说明 |
|---|---|
C-n / C-p 或 ↓ / ↑ | 上下移动 |
RET | 选择当前项 |
TAB | 补全公共部分 |
M-p / M-n | 历史上/下一条 |
C-l | 回到上级目录（文件操作时） |
C-u C-SPC | 跳回上一个位置 |
13.3 Marginalia（注解）
Marginalia 为 minibuffer 候选项添加丰富的注解信息。
(use-package marginalia
:init
(marginalia-mode 1)
:config
(setq marginalia-align 'right
marginalia-align-offset 1))
显示效果
M-x 输入 "buffer" 时：
buffer-menu Command: Display a list ...
buffer-menu-other-window Command: Display a list ...
buffer-menu*other-frame Command: Display a list ...
buffer-substring Command: Return the cont ...
buffer-name Command: Return the name ...
buffer-file-name Command: Return name of ...
buffer-modified-p Command: Return t if BUF ...
13.4 Orderless（匹配样式）
Orderless 让候选项匹配时支持空格分隔的多个模式，且顺序无关。
(use-package orderless
:config
(setq completion-styles '(orderless basic)
completion-category-defaults nil
completion-category-overrides '((file (styles partial-completion)))))
匹配示例
输入: "buf mod"
匹配:
✓ buffer-modified-p
✓ buffer-modestring
✓ modification
✓ buf-modify
输入: "file name$"
匹配:
✓ buffer-file-name （$ 表示行尾匹配）
✓ file-name
✗ filename-extension （不匹配）
匹配风格
| 风格 | 语法 | 示例 |
|---|---|---|
| 前缀 | 默认 | buf 匹配 buffer-menu |
| 后缀 | $ | name$ 匹配 file-name |
| 正则 | 正则 | buf.*mod |
| 字面 | 完全匹配 | = 前缀 |
| Flex | 顺序子串 | bm 匹配 buffer-menu |
13.5 Consult（搜索命令）
Consult 提供了丰富的搜索和导航命令。
(use-package consult
:bind (;; 缓冲区
("C-x b" . consult-buffer)
("C-x 4 b" . consult-buffer-other-window)
("C-x 5 b" . consult-buffer-other-frame)
;; 搜索
("C-s" . consult-line)
("M-s g" . consult-grep)
("M-s r" . consult-ripgrep)
("M-s l" . consult-line-multi)
;; 跳转
("M-g g" . consult-goto-line)
("M-g i" . consult-imenu)
("M-g I" . consult-imenu-multi)
;; 其他
("M-y" . consult-yank-pop)
("C-x C-r" . consult-recent-file))
:config
(setq consult-narrow-key "<"
consult-line-numbers-widen t))
Consult 核心命令
| 命令 | 说明 | 替代 |
|---|---|---|
consult-buffer | 模糊切换缓冲区 | switch-to-buffer |
consult-line | 当前文件搜索行 | isearch-forward |
consult-ripgrep | 项目级搜索 | grep / rgrep |
consult-goto-line | 跳转到行号 | goto-line |
consult-imenu | 符号跳转 | imenu |
consult-yank-pop | 剪贴板历史 | yank-pop |
consult-recent-file | 最近文件 | recentf-open-files |
consult-theme | 切换主题 | load-theme |
consult-flymake | 错误列表 | — |
13.6 Embark（上下文操作）
Embark 是"上下文菜单"，对光标处或选中的内容提供相关操作。
(use-package embark
:bind (("C-." . embark-act)
("C-;" . embark-dwim)
("C-h B" . embark-bindings))
:config
(setq embark-prompter 'embark-completing-read-prompter))
(use-package embark-consult
:after (embark consult)
:hook (embark-collect-mode . consult-preview-at-point-mode))
Embark 使用场景
在 minibuffer 中：
C-. → 打开操作菜单
e → 编辑候选内容
s → 保存到寄存器
w → 复制到 kill-ring
在文件路径上：
C-. → 打开操作菜单
f → 打开文件
d → 打开 Dired
r → 重命名文件
在 URL 上：
C-. → 打开操作菜单
b → 在浏览器中打开
d → 下载文件
s → 保存到书签
13.7 Corfu（代码补全 UI）
Corfu 是代码补全的 UI 框架，与 Vertico 配套。
(use-package corfu
:init
(global-corfu-mode 1)
:config
(setq corfu-auto t
corfu-auto-delay 0.2
corfu-auto-prefix 2
corfu-count 10
corfu-cycle t
corfu-quit-at-boundary 'separator
corfu-quit-no-match 'separator))
;; 可选：弹窗显示
(use-package corfu-popupinfo
:after corfu
:hook (corfu-mode . corfu-popupinfo-mode)
:config
(setq corfu-popupinfo-delay 0.5))
Corfu 操作
| 按键 | 说明 |
|---|---|
TAB | 补全公共部分或循环 |
S-TAB | 反向循环 |
RET | 选择并确认 |
C-g | 退出补全 |
M-n / M-p | 上下移动 |
13.8 Cape（补全后端）
Cape 提供多种补全后端，增强补全能力。
(use-package cape
:init
;; 添加补全后端
(add-to-list 'completion-at-point-functions #'cape-file)
(add-to-list 'completion-at-point-functions #'cape-dabbrev)
:config
;; 文件补全的额外配置
(setq cape-dabbrev-min-length 3))
Cape 补全后端
| 后端 | 说明 |
|---|---|
cape-file | 文件路径补全 |
cape-dabbrev | 动态缩写补全 |
cape-keyword | 关键字补全 |
cape-symbol | Elisp 符号补全 |
cape-ispell | 拼写补全 |
cape-dict | 字典补全 |
cape-line | 行补全 |
cape-history | 历史补全 |
cape-tex | TeX 符号补全 |
cape-emoji | Emoji 补全 |
13.9 Ivy/Counsel/Swiper（一体化方案）
Ivy 是一个成熟的一体化补全框架，适合追求开箱即用的用户。
(use-package ivy
:diminish ivy-mode
:init
(ivy-mode 1)
:config
(setq ivy-use-virtual-buffers t
ivy-count-format "(%d/%d) "
ivy-wrap t
ivy-initial-inputs-alist nil))
(use-package counsel
:after ivy
:bind (("M-x" . counsel-M-x)
("C-x C-f" . counsel-find-file)
("C-x b" . counsel-switch-buffer)
("M-y" . counsel-yank-pop)
("C-c f" . counsel-recentf)
("C-c g" . counsel-git-grep))
:config
(counsel-mode 1))
(use-package swiper
:after ivy
:bind ("C-s" . swiper))
(use-package ivy-rich
:after ivy
:init
(ivy-rich-mode 1))
Ivy vs Vertico 选择
你偏好开箱即用？
├── 是 → Ivy/Counsel/Swiper
└── 否 → 你想要最小依赖？
├── 是 → Vertico + Consult + Marginalia + Orderless + Embark
└── 否 → Helm（功能最全但最重）
13.10 完整的 Vertico 配置
;;; 完整的现代补全配置
;; 1. Vertico - Minibuffer 补全 UI
(use-package vertico
:init (vertico-mode 1)
:config
(setq vertico-count 15
vertico-resize t
vertico-cycle t))
;; 2. Orderless - 匹配样式
(use-package orderless
:config
(setq completion-styles '(orderless basic)
completion-category-overrides '((file (styles partial-completion)))))
;; 3. Marginalia - 注解
(use-package marginalia
:init (marginalia-mode 1))
;; 4. Consult - 搜索命令
(use-package consult
:bind (("C-x b" . consult-buffer)
("C-s" . consult-line)
("M-s g" . consult-grep)
("M-s r" . consult-ripgrep)
("M-g g" . consult-goto-line)
("M-g i" . consult-imenu)
("M-y" . consult-yank-pop)))
;; 5. Embark - 上下文操作
(use-package embark
:bind ("C-." . embark-act))
(use-package embark-consult
:after (embark consult))
;; 6. Corfu - 代码补全
(use-package corfu
:init (global-corfu-mode 1)
:config
(setq corfu-auto t
corfu-auto-delay 0.2))
;; 7. Cape - 补全后端
(use-package cape
:init
(add-to-list 'completion-at-point-functions #'cape-file)
(add-to-list 'completion-at-point-functions #'cape-dabbrev))
13.11 本章小结
| 包 | 用途 | 核心功能 |
|---|---|---|
| Vertico | Minibuffer UI | 候选列表显示 |
| Orderless | 匹配样式 | 无序多模式匹配 |
| Marginalia | 注解 | 候选项说明 |
| Consult | 搜索命令 | consult-buffer/line/ripgrep |
| Embark | 上下文操作 | embark-act 上下文菜单 |
| Corfu | 代码补全 UI | 弹窗补全 |
| Cape | 补全后端 | 文件、缩写、关键字 |
| Ivy | 一体化方案 | Counsel + Swiper 集成 |
| Helm | 重型方案 | 功能最全 |
13.12 扩展阅读
← 上一章 第 12 章：包管理 | 下一章 → 第 14 章：Git 集成