强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Emacs 完全指南 / 第 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 集成